Register Endpoint

The register endpoint allows dynamically registering an OpenID client.

Copy

The endpoint is exposed at the following URL (and can be obtained from the server discovery endpoint):

https://[base-server-url]/{tenant}/authn/register [POST]/[GET]/[PUT]/[DELETE]

Method Details

POST

GET

PUT

DELETE

Register Request

Copy

Sample request to register a client with a password

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",
    "post_logout_redirect_uris": ["https://client.example.org/logout", "https://client.example.org/logout2"],
    "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",
    "backchannel_token_delivery_mode": "poll",
    "hid_client_authentication_constraints": "0.0.0.0,10.16.125.223,10.16.124.0/32"
}

Register Response

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",
     "post_logout_redirect_uris": ["https://client.example.org/logout", "https://client.example.org/logout2"],
     "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",
     "hid_client_authentication_constraints": "10.16.125.223,10.16.124.0/32"
}

Error Responses

Code	Label	Possible Errors
400	BAD REQUEST	No client found
401	UNAUTHORIZED	Invalid_token
403	FORBIDDEN	insufficient_scope
409	CONFLICT	duplicate_client

Required Parameters

Parameter	Description
`redirect_uris`	Array of URIs to which the response of the authorization request will be sent, and which must match one that has been registered during client registration. For further information, see the OpenID Connect Dynamic Client Registration specification – section 3.

Optional Parameters

Parameter	Description
`client_name`	This is could be description of the client. If present, and client_id is not passed as a parameter, it is used (combined with redirect_uris) to generate the unique client_id.
`client_id`	Must be unique. If present, the client is registered with this client_id. If not present, a unique id is generated by server and returned in the response. Note: If client_id is present, it is assumed to have unicity, and the format respects the user ID constraints. Otherwise, errors will be returned in the response.
`token_endpoint_auth_method`	Supported values are: client_secret_basic client_secret_post client_secret_pki private_key_jwt self_signed_tls_client_auth none
`jwks`	If token_endpoint_auth_method is private_key_jwt, it can contain a list of public keys/certificates. The one for PKI credential should have no specified key use. It can contain key/certificate with key use “sig” or “enc”.
`jwks_uri`	If token_endpoint_auth_method is private_key_jwt, this parameter or jwks is required. One of the two parameters must be present and the uri present must be accessible from server. Note: The jwks_uri parameter is not supported in for OpenID request objects.
`client_secret`	Only used when performing an UPDATE to reset a client password.
`id_token_encrypted_response_alg`	Algorithm to encrypt id_token in token endpoint. If empty, id_token is not encrypted. The recommended algorithm is RSA-OAEP-256.
`userinfo_encrypted_response_alg`	Algorithm to encrypt the UserInfo response. If empty, the response is not encrypted. The recommended algorithm is RSA-OAEP-256.
`userinfo_signed_response_alg`	Algorithm to sign the UserInfo response: If empty, the JWT response is not signed. If set to RS256, the JWT response is signed by the Identity Provider’s signature key (that is advertised in the JWKS endpoint) with RS256 algorithm. If set to none, the response is returned in the plain JSON format (unsigned).
`backchannel_token_delivery_mode`	Defines if CIBA feedback is sent using the push (default) or poll mode. For further information about the modes, see the OpenID Connect CIBA Core specifications - section 5 .
`require_pushed_authorization_requests`	Defines if PAR is required in HID Authentication Service Possible values are: true false (default)
`post_logout_redirect_uris`	Array of URIs checked when the post_logout_redirect_uri is present in the logout request. If no exact match is found with the URIs in the list, the logout request is rejected If missing, the URIs defined for redirect_uris are checked and, if no exact match is found, the logout request is rejected
`id_token_hint_issuers`	Array of external issuers from which the id_token_hint can be accepted

Optional HID Custom Parameters

Parameter	Description	Default value	Property
`hid_client_channel`	Channel through which the client authenticates	CH_DIRECT	OpenId.DEFAULT_RP_CLIENTCHANNEL
`hid_client_pwd_policy`	Password-based authentication policy to use to authenticate the client	AT_SYSLOG	OpenId.DEFAULT_RP_CLIENTCREDAUTHPOL
`hid_client_pki_policy`	PKI-based authentication policy to use to authenticate the client	AT_SYSPKI	OpenId.DEFAULT_RP_CLIENTPKIAUTHPOL
`hid_client_credential_type`	Credential type for authentication type configured for OpenID client authentication if the authentication type is configured with several credential types	Not applicable Note: This parameter is not present by default, and does not have a default value or associated property.
`hid_user_channel`	Channel through which an end user of the client authenticates	CH_TDSPROV	OpenId.DEFAULT_RP_USERCHANNEL
`hid_user_authn_policy`	Default authentication policy for the end user	AT_TDSOOB	OpenId.DEFAULT_RP_USERPWDAUTHPOL
`hid_sessiontransfer_type`	Type of the transfer policy for the session's authorization code	NUM001	OpenId.DEFAULT_RP_USERSESSIONTRANSFTYPE
`hid_client_group`	Default user group for the client	USG_SYS	OpenId.DEFAULT_RP_USERPARENTGROUP
`hid_client_authentication_constraints`	Whitelist of IP addresses allowed to authenticate the OpenID client The supported value is a comma-separated list containing individual, or a range of, IP addresses as a string: Individual IP - supports the IPv4 or IPv6 protocols (for example, 10.16.125.223) IP range - defined by CIDR block allocation (for example, 10.16.124.0/32) The value can contain both individual and ranges. For example: "10.16.125.223,10.16.124.0/32" If the parameter is not present or undefined, no IP restriction will be applied for OpenID client authentication	Not applicable Note: This parameter is not present by default, and does not have a default value or associated property.

The default session transfer policies are:

Policy name	Format	Expiry period	Length
NUM001	Numeric	10 minutes	8 digits
NUM002	Numeric	3 minutes	20 digits
ALP001	Alphabetic	10 minutes	8 digits
ALP002	Alphabetic	3 minutes	20 digits
ANU001	Alphanumeric	10 minutes	8 digits
ANU002	Alphanumeric	3 minutes	20 digits

Optional HID Custom Parameters for End-User Consent Signing

Parameter	Description
`hid_client_scopes`	Considered as the “openid profile”, and the default value is empty.
`hid_client_consentprompt`	Defines whether to prompt the end user for sign their consent in the authorization flow, and the default value is true.

Optional HID Custom Parameters for Domain Federation

These parameters are taken into account only when domain federation is required.

Parameter	Description
`hid_federation_audiences`	Defines the valid audiences (using a regular expression based on the syntax format described in https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). If the audiences are OpenID clients and the SSO is enabled for these clients (as defined in hid_sso_session_validity), they are allowed to access the SSO session of the current client. Add the OpenID client ID of the application(s) allowed to use the user's authenticated session, where the format of the value should be a regular expression. As examples for the following use cases: To allow access for one or more applications, use the format client_ID1\|client_ID2 To allow access for all clients with a specific ID (for example, starting with 'HID', set the value as ^HID.*
`hid_federation_roles`	Defines the filter of roles (using a regular expression) that will be sent to the Managed Domains as part of the JWT access token.
`hid_federation_atttype`	Attribute type created previously to publish dedicated identities per Oauth2 client application.
`hid_federation_channel`	Post-authentication channel(s) for domain federation. Values can be a single channel or list of channels separated by \| (for example, "CH_IIS\|CH_VPN").

Optional HID Custom Parameters for Refresh Token

Parameter Description

Parameter	Description
`hid_refresh_token_validity`	Lifetime of a refresh token (in seconds and must be greater than 0) If it is not present in the request, the value of hid_sessiontransfer_type is used as the refresh token validity, (that is, if hid_sessiontransfer_type is “NUM001”, the validity is 600 seconds).

hid_refresh_token_validity

Lifetime of a refresh token (in seconds and must be greater than 0)

If it is not present in the request, the value of hid_sessiontransfer_type is used as the refresh token validity, (that is, if hid_sessiontransfer_type is “NUM001”, the validity is 600 seconds).

Optional HID Custom Parameters for ID Token Signature/Encryption and Format

Parameter Description

Parameter	Description
`hid_ciba_callback_format_plain`	Defines if the ID Token in the CIBA the response should be signed (or signed/encrypted) and use the updated format that complies with the CIBA specifications. By default (or if not present), this parameter is set to false so the ID Token will be signed or signed/encrypted and use the updated format. To disable the signature or signature/encryption of the ID Token and use the plain format, set the parameter to true. Optionally, you can also configure the OpenID client for ID Token encryption using the id_token_encrypted_response_alg and jwks parameters (where the currently supported algorithm is RSA-OAEP-256).

hid_ciba_callback_format_plain

Defines if the ID Token in the CIBA the response should be signed (or signed/encrypted) and use the updated format that complies with the CIBA specifications.

By default (or if not present), this parameter is set to false so the ID Token will be signed or signed/encrypted and use the updated format.

To disable the signature or signature/encryption of the ID Token and use the plain format, set the parameter to true.

Optionally, you can also configure the OpenID client for ID Token encryption using the id_token_encrypted_response_alg and jwks parameters (where the currently supported algorithm is RSA-OAEP-256).

Optional HID Custom Parameters for Pushed Authorization Requests (PAR)

Parameter Description

Parameter	Description
`pushed_authorization_request_validity`	Defines the validity period of the PAR request (in seconds and must be greater than 0) The default value is 600 Note: In the specifications OAuth 2.0 Pushed Authorization Requests, the recommended values are 5-600 seconds.

pushed_authorization_request_validity

Defines the validity period of the PAR request (in seconds and must be greater than 0)

The default value is 600

Note: In the specifications OAuth 2.0 Pushed Authorization Requests, the recommended values are 5-600 seconds.

Optional HID Custom Parameters for the IdP

For further details, see Apply Your IdP Configuration.

Parameter	Description
`initiate_login_uri`	Define the URI where the login page will be redirected (optional) If present, the value must be the URI of interface handling the IdP flow. Note: This parameter is reserved for future use and should be left empty to allow use of the default HID portal. HID Authentication Service checks it is a valid URI format (should be absolute URI path) and the login page will be redirected to this URI. If empty, the new portal URL will be computed with the deployment URI and tenant
`authn_portal_configuration`	An array of the IdP parameter in the JSON format (the format is validated during the register and update operations). If the parameters are present, the new IdP will be used based on the defined values If empty, (set the value to " " when empty), the standard HID Authentication Serviceinterface is displayed It contains the following parameters:
	`workflow_id` - the unique identifier of the authentication configuration definition to be used for the client (mandatory) The content of configuration defines the flow and authentication factors. See Create the Authentication Workflow. If absent or contains an incorrect ID, the OpenID client registration returns error.
	`theme_id` - the unique identifier for theme definition (optional) The content of the theme defines the customization for application interface such as titles and labels. See Customizing the Identity Portal. If empty, the default theme is used.
`hid_sso_session_validity`	For the client application(s) that will use an SSO session of another client, define the maximum age limit of the existing SSO session (in seconds and greater than 0). If a user tries to log on after this limit is reached, and even if the initial authenticated session is still valid, they will be required to re-authenticate. The default value is 0 and if the parameter is not present (or set to 0), SSO support is disabled. You must also set the allowed client IDs in the hid_federation_audiences parameter.