Skip to content

Latest commit

 

History

History
130 lines (107 loc) · 6.3 KB

dynamic_registration.adoc

File metadata and controls

130 lines (107 loc) · 6.3 KB
Raw

Dynamic Registration

Note
Not available

Dynamic Registration is currently not enabled but will be made available to developers in the future.

Another way of registering clients is through the dynamic register method defined on the OAuth2.0 specification and extended to allow OpenID Connect parameters. This method allows the client to automatically register itself, receiving all the necessary parameters in order to integrate to the security service. Clients registered using this method will inevitably have an expiration date and its usage implies the necessity of restricting the use of the functionality to avoid exploits or security breaches.

In order to register a new client, a call must be performed to the register API Endpoint. The only mandatory parameters are redirect_uris and client_name. The rest of the parameters on this request are completely optional, which means that the Authorization Server will fill in values by default. In any case, the client can initially create a client with default configuration and update it afterward using methods described in this section.

  • Register Endpoint (POST): /oxauth/restv1/register

    • redirect_uris (mandatory): array of strings containing the redirect_uris for the client

    • client_name (mandatory): string containing the client name

    • response_types: array of strings containing the desired response types

    • grant_types: array of strings containing the desired grant types

    • application_type: can either be "web" or "native"

    • subject_type: can either be pairwise (each user is assigned a unique "sub" parameter) or public

    • token_auth_method: identifies the authentication method when retrieving tokens from the Token Endpoint

    • default_max_age: indicates the max age for tokens obtained using this client

    • default_acr_values: there is no need to assign any value to this parameter, but if set to "passport", it will redirect the user to the mediation service.

    • [Other parameters]

There is a wide variety of parameters that can be configured on this request and all of them can be checked on the discovery document:

Disovery document JSON:
GET /.well-known/openid-configuration

For example, if the client wants to use signed JSON Web Tokens, it is necessary to include the corresponding parameter in the call to the Register Endpoint. The discovery document has a field named "id_token_signed_response_alg_values_supported" with several signing methods. One of them can be selected by the client and passed through the parameter "id_token_signed_response_alg".

There is only ONE parameter that is not configurable through this dynamic method and that is the "scopes" parameter. These are filled in by the authorization server for security purposes based on the parameters received on the request. Testbed-14 behavior will be to assign the same limited scopes to all dynamic clients, but it is possible to restrict scopes based on domain, grant_types or any other parameter.

Any call to the Register Endpoint will have the Authorization Server answer back with a JSON document that indicates metadata about the recently generated client. In particular, there will be two additional fields that can be of use to the client and those are:

  • registration_access_token: a bearer token that allows the requester to list or modify metadata about a specific client

  • registration_client_uri: a URI assigned to a specific client for further interactions

There are mainly two more actions that can be performed with these parameters:

Client metadata retrieval:
GET <registration_client_uri> -H "Authorization: Bearer registration_access_token"
Client metadata update:
PUT <registration_client_uri> -H "Authorization: Bearer registration_access_token" + JSON_BODY

Basic example

The most basic example for dynamic client registration would be:

Example:
POST /oxauth/restv1/register
{
         "redirect_uris": [
              "https://client.example.org/callback",
              "https://client.example.org/callback2"
          ],
         "client_name": "Basic Client"
}

The Authorization Server would respond with the following information (example):

Example of registration response:
{
  "client_id": "@!27B7.E085.07A1.6DE7!0002!F5E4.0B8E!0008!C14A.232C.E89C.C514",
  "client_secret": "b2a5fc13-3593-4100-8287-db844b4845f2",
  "registration_access_token": "dee762cf-b134-4e2b-81fd-1238c9299135",
  "registration_client_uri": "https://testbed14-sso.elecnor-deimos.com/oxauth/restv1/register?client_id=@!27B7.E085.07A1.6DE7!0002!F5E4.0B8E!0008!C14A.232C.E89C.C514",
  "client_id_issued_at": 1533812916,
  "client_secret_expires_at": 1533816516,
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "response_types": ["code"],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "application_type": "web",
  "client_name": "Basic Client",
  "subject_type": "pairwise",
  "id_token_signed_response_alg": "RS256",
  "token_endpoint_auth_method": "client_secret_basic",
  "require_auth_time": false,
  "frontchannel_logout_session_required": false,
  "scopes": [
    "openid",
    "uma_protection",
    "permission",
    "user_name",
    "email",
    "profile"
  ]
}

Behavior by default is to utilize the Authorization Code grant, allowing refresh tokens, and the default set of scopes can be seen in the example. The client secret has also been randomly generated.

End-User clients

POST /oxauth/restv1/register
{
      "redirect_uris": [
        "https://client.example.org/callback",
        "https://client.example.org/callback2"],
      "client_name": "D142 Client",
      "token_endpoint_auth_method": "client_secret_post",
      "response_types": ["token", "id_token", "code"],
      "default_acr_values": ["passport"],
}

The "default_acr_values" set to "passport" allows the service to be redirected through a mediation service (with federation options).

Testing client (for service implementers)

POST /oxauth/restv1/register
{
      "redirect_uris": [
        "https://client.example.org/callback"],
      "client_name": "WFS Service Example",
      "token_endpoint_auth_method": "client_secret_post",
      "grant_types": ["password"]
}