Client Registration Samples

The following sections provide samples of the requests/responses for dynamic OpenID client registration.

Register a Client with a Password

See also http://openid.net/specs/openid-connect-registration-1_0.html#RegistrationRequest

Sample Request

Copy 
POST https://[base-server-url]/{tenant}/authn/register HTTP/1.1
Content-Type: application/json
Authorization: Bearer RTp7HwAAAV6kDLkStyOElco4/XqhuFOnqCHTypGu
 
{
    "redirect_uris": ["https://client.example.org/callback", "https://client.example.org/callback2"],
    "client_name": "OpenID Client 1",
    "client_id": "openid_client31",
    "token_endpoint_auth_method": "client_secret_basic",
    "hid_client_channel": "CH_SSP",
    "hid_client_pwd_policy": "AT_SYSLOG",
    "hid_client_pki_policy": "AT_CUSTPKI",
    "hid_user_channel": "CH_IIS",
    "hid_user_authn_policy": "AT_CUSTPW",
    "hid_sessiontransfer_type": "NUM002",
    "hid_client_group": "USG_SYS",
    "hid_federation_audiences": "ENTERPRISE",
    "hid_federation_roles": ".*",
    "hid_federation_atttype": "OAUTHFEDID"
    "hid_federation_channel": "CH_SSP|CH_IIS"
}

In this sample request, the following fields are important:

Parameter Description

redirect_uris

(Required) client_name and redirect_uris are used to calculate a unique client id.

token_endpoint_auth_method

(Optional) Supported methods for client with password are both client_secret_basic and client_secret_post which means that even if client_secret_basic is requested, client_secret_post is also supported.

client_name

(Optional) Name of the client application

client_id

(Optional) Useful if the client has its own format of client_id.

If this parameter is not present, a generated client_id is returned.

For further information about these fields, see Supported Parameters for OpenID Client Registration Requests.

Sample Responses

See also http://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse

Copy

Success

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
 
{
    "hid_sessiontransfer_type": "NUM002",
    "grant_types": [ "client_credentials", "password", "authorization_code" ],
    "hid_client_group": "USG_SYS",
    "registration_client_uri": "https://[base-server-url]/{tenant}/authn/register/446646871533782685669055465855092625634211188751",
    "redirect_uris": [ "https://client.example.org/callback", "https://client.example.org/callback2" ],
    "hid_client_channel": "CH_SSP",
    "token_endpoint_auth_method": "client_secret_basic",
    "client_id": "openid_client31",
    "hid_client_pwd_policy": "AT_SYSLOG",
    "hid_client_pki_policy": "AT_CUSTPKI",
    "hid_user_channel": "CH_IIS",
    "client_secret_expires_at": 1663671361,
    "hid_user_authn_policy": "AT_CUSTPW",
    "client_id_issued_at": 1505991361,
    "client_secret": "OpenID1505991361480",
    "client_name": "OpenID Client 1",
    "hid_federation_audiences": "ENTERPRISE",
    "hid_federation_roles": ".*",
    "hid_federation_atttype": "OAUTHFEDID"
    "hid_federation_channel": "CH_SSP|CH_IIS"
}

In this response, the following fields are important:

Parameter Description

registration_client_uri

For future operations such as delete.

client_secret

Always generated by server, not taken from the request.

client_id

Identifier of the client.
Copy

Error 1

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="Invalid access token"
Copy

Error 2

HTTP/1.1 400 Bad Request
 
{
    "error_description": "",
    "error": "com.actividentity.service.iasp.channel.NoSuchChannelException"
}
Note: “error" can be informative and normally corresponds to exceptions generated on the back end.
Copy

Error 3

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", error_description="Insufficient scope"
Copy

Error 4

HTTP/1.1 409 Conflict
 
{
    "error_description": "A user with this code already exists.<Domain: ONLINEBANK>",
    "error": "duplicate_client"
}

Register a Client with PKI Credentials

Sample Request

Copy 
POST https://[base-server-url]/{tenant}/authn/register HTTP/1.1Content-Type: application/json
Authorization: Bearer RTp7HwAAAV6kDLkStyOElco4/XqhuFOnqCHTypGu
 
{
    "redirect_uris": ["https://client.example.org/callback", "https://client.example.org/callback2"],
    "client_name": "openid_client31",
    "client_id": "openid_client31",
    "token_endpoint_auth_method": "private_key_jwt",
    "hid_client_channel": "CH_SSP",
    "hid_client_pwd_policy": "AT_SYSLOG",
    "hid_client_pki_policy": "AT_MCPKI",
    "hid_user_channel": "CH_IIS",
    "hid_user_authn_policy": "AT_CUSTPW",    
    "hid_sessiontransfer_type": "NUM002",
    "hid_client_group": "USG_USRADM",
    "jwks": {"keys":[{"kty":"RSA","x5t#S256":"ZFgZlr5qYFHyWtKzsHk1rja2chRcshc4NrWkYFrvoio","e":"AQAB","kid":"379112668518902081505018885217414831543418907","x5c":["MIIGNTCCBR2gAwIBAgITEQAAABu157H0suxxbwAAAAAAGzANBgkqhkiG9w0BAQsFADBpMRMwEQYKCZImiZPyLGQBGRYDY29tMRIwEAYKCZImiZPyLGQBGRYCYWkxGDAWBgoJkiaJk\/IsZAEZFghBRklXMjAxMjEkMCIGA1UEAxMbQUZJVzIwMTItV0lOLUdGU01QUUtTMzQ4LUNBMB(…)
7dlizqis0Fq0kLoWbEbLfiItUGeBctm9JDOJdZ9lil2PGjCkP4_ofIoLHy8QDA68Z38g99amZOoBVhA0gYeqUPg81gr4cvdQSj5iAZ2hDEFFN3ae5E60gxAaUsqNarAlQaP9P6XHws1l674V9YdCO5Y2WRdirv693grckBmN5Oqvw6AN8cA17HVpE1w"}]}
}

In this sample request, the following fields are important:

Parameter Description

jwks

(Required) contains a list of keys/certificates, and one of these must contain a valid x509 certificate with null “use” value (see Configuring Support for OpenID Connect Request Objects).

If this field is missing, and token_endpoint_auth_method is NOT client_secret_basic or client_secret_post, an error will be returned.

client_name

(Optional) human readable name.

If present, it is used (combined with redirect_uris) to generate the unique client_id.

client_id

(Optional) useful if the client has its own format of client_id.

If this parameter is not present, a generated client_id is returned.

For further information about these parameters, see Supported Parameters for OpenID Client Registration Requests.

Sample Responses

See also http://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse

Copy

Success

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
 
{
    "hid_sessiontransfer_type": "NUM002",
    "jwks": 
        {"keys":[{"kty":"RSA","x5t#S256":"ZFgZlr5qYFHyWtKzsHk1rja2chRcshc4NrWkYFrvoio","e":"AQAB","kid":"379112668518902081505018885217414831543418907","x5c":["MIIGNTCCBR2gAwIBAgITEQAAABu157H0suxxbwAAAAAAGzANBgkqhkiG9w0BAQsFADBpMRMwEQYKCZImiZPyLGQBGRYDY29tMRIwEAYKCZImiZPyLGQBGRYCYWkxGDAWBgoJkiaJk\/IsZAEZFghBRklXMjAxMjEkMCIGA1UEAxMbQUZJVzIwMTItV0lOLUdGU01QUUtTMzQ4LUNBMB(…)
7dlizqis0Fq0kLoWbEbLfiItUGeBctm9JDOJdZ9lil2PGjCkP4_ofIoLHy8QDA68Z38g99amZOoBVhA0gYeqUPg81gr4cvdQSj5iAZ2hDEFFN3ae5E60gxAaUsqNarAlQaP9P6XHws1l674V9YdCO5Y2WRdirv693grckBmN5Oqvw6AN8cA17HVpE1w"}]},
    "hid_client_group": "USG_USRADM",
    "registration_client_uri": "https://server.example.com:8445/idp/domain/authn/register/openid_client30",
    "redirect_uris":  [ "https://client.example.org/callback", "https://client.example.org/callback2" ],
    "hid_client_channel": "CH_SSP",
    "token_endpoint_auth_method": "private_key_jwt",
    "client_id": "openid_client31",
    "hid_client_pwd_policy": "AT_SYSLOG",
    "hid_client_pki_policy": "AT_MCPKI",
    "hid_user_channel": "CH_IIS",
    "hid_user_authn_policy": "AT_CUSTPW",
    "client_id_issued_at": 1505997942,
    "client_id": "openid_client30",
    "client_name": "openid_client31"
}

In this response, the following fields are important as the OpenID client needs to keep this information for future OpenID operations:

  • registration_client_uri – for future operations such as unregister or get registration information.

  • client_id – identifier of the client.

Copy

Error 1

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="Invalid access token"
Copy

Error 2

HTTP/1.1 400 Bad Request
 
{
"error_description": "",
"error": "com.actividentity.service.iasp.user.InvalidUserException"
}
Copy

Error 3

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", error_description="Insufficient scope"
Copy

Error 4

HTTP/1.1 400 Bad Request
 
{
"error_description": "",
"error": "com.actividentity.service.iasp.user.DuplicateUserException"
}

Unregister a Client

To unregister OpenID client, send a DELETE HTTP request to the registration_client_uri (returned by the registration response).

The DELETE HTTP method is used to delete a registration.

A successful registration deletion will:

  • Delete the OpenID adapter.
  • Delete the authentication record and credentials corresponding to registered authentication policy (defined in the adapter's parameters).
  • Delete the device if no other credentials remain in this device.
  • Delete the user if no other credentials remain for this user.

Sample Request

Copy 
DELETE https://[base-server-url]/{tenant}/authn/register/{client_id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer RTp7HwAAAV6kDLkStyOElco4/XqhuFOnqCHTypGu

Sample Responses

Copy

Success

HTTP 204 No Content
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Copy

Error 1

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="Invalid access token"
Copy

Error 2

HTTP/1.1 400 Bad Request
 
{
"error_description":"No client found",
"error":"com.actividentity.idp.backend.exceptions.InvalidOauthRequestException"
}
Copy

Error 3

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", error_description="Insufficient scope"

Get a Client’s Registration Information

To get information about a registered OpenID client, send a GET HTTP request to the registration_client_uri (returned by the registration response).

Note: No client secret or jwks is returned in the GET response.

Sample Request

Copy 
GET https://[base-server-url]/{tenant}/authn/register/{client_id} HTTP/1.1Content-Type: application/json
Authorization: Bearer Z+KhhwAAAWEDniElkzhN22+NzIrUVXCeMTemsuDb

Sample Responses

Copy

Success

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
 
{
"hid_sessiontransfer_type": "NUM002",
"grant_types": ["urn:hid:oauth:grant-type:client-secret-pki"],
"registration_client_uri": "https://server.example.com:8445/idp/domain/authn/register/155624413935386655761948344737012242832594665791",
"redirect_uris": ["https://client.example.org/callback2","https://client.example.org/callback"],
"hid_client_channel": "CH_SSP",
"token_endpoint_auth_method": "private_key_jwt",
"client_id": "openid_client31",
"hid_client_pwd_policy": "AT_SYSLOG",
"hid_client_pki_policy": "AT_MCPKI",
"hid_user_channel": "CH_IIS",
"hid_user_authn_policy": "AT_CUSTPW",
"client_id_issued_at": 1506940113,
"client_name": "openid_client30"
}
Copy

Error 1

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="Invalid access token"
Copy

Error 2

HTTP/1.1 400 Bad Request
 
{
"error_description":"No client found",
"error":"com.actividentity.idp.backend.exceptions.InvalidOauthRequestException"
}
Copy

Error 3

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", error_description="Insufficient scope"

Update a Client’s Registration Information

To update registered information for an OpenID client, send a PUT HTTP request to the register endpoint.

The only required parameter is client_id.

The following parameters are optional, and can be present depending on the use case (see Sample Requests).

Parameter Description
hid_client_group

NOT supported. If present, no error is returned but the user group will not be changed.
client_secret

Changes a client's static password.

If the client does not have a static password, creates a new one with the defined value and the corresponding authentication policy (as set in the hid_client_pwd_policy parameter).
jwks

Changes a client's PKI credential.

If the client does not have a PKI credential, creates a new one with the corresponding authentication policy (as set in the hid_client_pki_policy parameter).
redirect_uris

Changes the value in the OpenID adapter configuration.
client_name

Changes the value in the OpenID adapter configuration.
hid_client_channel

Changes the value in the OpenID adapter configuration.
hid_client_pwd_policy

Changes the value in the OpenID adapter configuration.

If client_secret is present, creates a static password with authentication type set in this parameter. If a password already exists, it is deleted and replaced by the new one.
hid_client_pki_policy

Changes the value in the OpenID adapter configuration.

If jwks is present, creates a PKI credential with authentication type set in this parameter. If a PKI credential already exists, it is deleted and replaced by the new one.
hid_user_channel

Changes the value in the OpenID adapter configuration.
hid_user_authn_policy

Changes the value in the OpenID adapter configuration.
hid_sessiontransfer_type

Changes the value in the OpenID adapter configuration.
hid_client_scopes

Changes the value in the OpenID adapter configuration.
hid_federation_audiences

Changes the value in the OpenID adapter configuration.
hid_federation_roles

Changes the value in the OpenID adapter configuration.
hid_federation_atttype

Changes the value in the OpenID adapter configuration.
hid_client_consentprompt

Changes the value in the OpenID adapter configuration.
hid_refresh_token_validity

Changes the value in the OpenID adapter configuration.

For further information about these parameters, see Supported Parameters for OpenID Client Registration Requests.

Sample Requests

Copy 
PUT https://[base-server-url]/{tenant}/authn/register HTTP/1.1Content-Type: application/json
Authorization: Bearer Z+KhhwAAAWEDniElkzhN22+NzIrUVXCeMTemsuDb
 
{
"redirect_uris": ["https://client.example.org/callback","https://client.example.org/callback2"],
"client_name": "openid_client30",
"client_id": "openid_client30",
"hid_client_channel": "CH_SSP",
"hid_client_pwd_policy": "AT_SYSLOG",
"hid_client_pki_policy": "AT_CUSTPKI",
"hid_user_channel": "CH_SSP",
"hid_user_authn_policy": "AT_CUSTPW",
"hid_sessiontransfer_type": "NUM002",
"hid_client_group": "USG_SYS",
"hid_client_scopes": "{\"scopes\":[\"openid\":{\"claims\":{\"userinfo\":{\"usr.TITLE\":{\"essential\": true},\"usr.DOB\": {\"essential\": false}},\"id_token\":{\"usr.groupids\":{\"essential\": true},\"usr.roles\":{\"essential\": false},\"acr\": {\"essential\": true}}}}},\"profile\"]}",
"hid_federation_audiences": "ENTERPRISE",
"hid_federation_roles": "s.*",
"hid_federation_atttype": "OAUTHFEDID"
}
Copy

Sample request to change client's static password

PUT https://[base-server-url]/{tenant}/authn/register HTTP/1.1Content-Type: application/json
Authorization: Bearer Z+KhhwAAAWEDniElkzhN22+NzIrUVXCeMTemsuDb
 
{
"client_id": "openid_client53",
"hid_client_pwd_policy": "AT_SYSLOG",
"client_secret":"password03",
"token_endpoint_auth_method": " client_secret_basic"}
  • If the client already has a static password, it is replaced by a new one.
  • If the client does not have a static password, one is created.
Copy

Sample request to change PKI credential

PUT https://[base-server-url]/{tenant}/authn/register HTTP/1.1Content-Type: application/json
Authorization: Bearer Z+KhhwAAAWEDniElkzhN22+NzIrUVXCeMTemsuDb
 
{
"client_id": "openid_client52",
"hid_client_pki_policy": "AT_SYSPKI",
"token_endpoint_auth_method": "private_key_jwt",
"jwks": {"keys":[{"kty":"RSA","x5t#S256":"ZFgZlr5qYFHyWtKzsHk1rja2chRcshc4NrWkYFrvoio","e":"AQAB","use":"enc","kid":"379112668518902081505018885217414831543418907","x5c":["MIIGNTCCBR2gAwIBAgITEQAAABu157H0suxxbwAAAAAAGzANBgkqhkiG9w0BAQsFADBpMRMwEQYKCZImiZPyLGQBGRYDY29tMRIwEAYKCZImiZPyLGQBGRYCYWkxGDAWBgoJkiaJk\/IsZAEZFghBRklXMjAxMjEkMCIGA1UEAxMbQUZJVzIwMTItV0lOLUdGU01QUUtTMzQ4LUNBMB
(…)
I0ttB6LpPW4c0NrMXn4cB2pfI6mpTa2mjM4qPX8DhI8T610go9ue0kW2Vm2ykJdqL6ov5sG_J0UJHWKFxOCdUOjjeVaN7iVf9y8A_9iQ7G581DZDG8gEw-7dlizqis0Fq0kLoWbEbLfiItUGeBctm9JDOJdZ9lil2PGjCkP4_ofIoLHy8QDA68Z38g99amZOoBVhA0gYeqUPg81gr4cvdQSj5iAZ2hDEFFN3ae5E60gxAaUsqNarAlQaP9P6XHws1l674V9YdCO5Y2WRdirv693grckBmN5Oqvw6AN8cA17HVpE1w"}]},
}
  • If the client already has a PKI credential, it is replaced by a new one.
  • If the client does not have a PKI credential, one is created.
Copy

Sample request to update OpenID client configuration only

PUT https://[base-server-url]/{tenant}/authn/register HTTP/1.1Content-Type: application/json
Authorization: Bearer Z+KhhwAAAWEDniElkzhN22+NzIrUVXCeMTemsuDb
 
{
"redirect_uris": ["https://client.example.org/callback", "https://client.example.org/callback2"],
"client_name": "openid_client30",
"client_id": "openid_client30",
"hid_client_channel": "CH_SSP",
"hid_client_pwd_policy": "AT_SYSLOG",
"hid_client_pki_policy": "AT_CUSTPKI",
"hid_user_channel": "CH_SSP",
"hid_user_authn_policy": "AT_CUSTPW",
"hid_sessiontransfer_type": "NUM002",
"hid_client_scopes": "{\"scopes\":[\"openid\":{\"claims\":{\"userinfo\":{\"usr.TITLE\":{\"essential\": true},\"usr.DOB\": {\"essential\": false}},\"id_token\":{\"usr.groupids\":{\"essential\": true},\"usr.roles\":{\"essential\": false},\"acr\": {\"essential\": true}}}}},\"profile\"]}",
"hid_federation_audiences": "ENTERPRISE",
"hid_federation_roles": "s.*",
"hid_federation_atttype": "OAUTHFEDID"
}

Updates the OpenID client parameters (OpenID adapter configuration) but not the client’s credential(s).

Sample Responses

Copy

Success

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
 
{
"hid_sessiontransfer_type": "NUM002",
"hid_federation_atttype": "OAUTHFEDID",
"mutual_tls_sender_constrained_access_tokens": false,
"hid_federation_audiences": "ENTERPRISE",
"registration_client_uri": "https://server.example.com:8445/idp/domain/authn/register/openid_client30",
"redirect_uris": [ "https://client.example.org/callback", "https://client.example.org/callback2"],
"hid_client_channel": "CH_SSP",
"client_id": "openid_client30",
"hid_federation_roles": "s.*",
"hid_client_pwd_policy": "AT_SYSLOG",
"hid_client_pki_policy": "AT_CUSTPKI",
"hid_client_scopes": "{\"scopes\":[\"openid\":{\"claims\":{\"userinfo\":{\"usr.TITLE\":{\"essential\": true}, \"usr.DOB\": {\"essential\": false}},\"id_token\":{\"usr.groupids\":{\"essential\": true},\"usr.roles\":{\"essential\": false},\"acr\": {\"essential\": true}}}}},\"profile\"]}",
"hid_user_channel": "CH_SSP",
"hid_user_authn_policy": "AT_CUSTPW",
"client_id_issued_at": 1516370852,
"client_name": "openid_client30"
}
Copy

Error 1

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="Invalid access token"
Copy

Error 2

HTTP/1.1 400 Bad Request
 
{
"error_description":"No client found",
"error":"com.actividentity.idp.backend.exceptions.InvalidOauthRequestException"
}
Copy

Error 3

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", error_description="Insufficient scope"