Your suggested change has been received. Thank you.
Download OpenAPI specification:Download
This API mechanisms is for dynamically registering clients with authorization servers. This API covers registration of OpenID Connect (OIDC) clients.
Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol.
Conformance
This API is fairly conformant to the OpenID Connect Dynamic Client Registration 1.0 specification, see OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1. iWelcome supports only the Protected Dynamic Client Registration and does not support Open Dynamic Client Registration: when registering a client a valid access_token is required having appropriate authorisation.
It does not support the full set of client metadata. The following are not supported:
This API is fairly conformant to the RFC's for OAuth client registration: RFC-7591 and RFC-7592. Updating a registered client (using a PUT method on the registration endpoint) is not supported. The schema for registered clients does not support the following attributes:
Note: iWelcome does support client registration of public clients and confidential clients.
iWelcome Extension
iWelcome has extended the schema for clients:
iWelcome has added an additional endpoint to delete a client, resulting in two 'delete endpoints':
API Security
All endpoints in this API are protected endpoints. They require a valid OAuth access_token. More specifically:
Performance Considerations
The number of OAuth clients that are registered may impact the performance of iWelcome's support for the various OAuth and OIDC endpoints. iWelcome currently does not guarantee any performance when more than 200 OAuth clients are registered, either via client.
The client registration endpoint is an OAuth 2.0 endpoint defined in OpenID Connect Dynamic Client Registration 1.0 specification that is designed to allow a client to be registered with the authorization server. iWelcome's initial implementation supports a limited set of client metadata. iWelcome ignores any client metadata sent by the client that it does not understand.
Security
The client registration endpoint is protected by a transport-layer security mechanism. The client registration endpoint is a protected endpoint; clients need to provide a valid access_token. The access_token needs to have a scope 'dynamic-client-registration'.
Authorization required | string Bearer |
The client payload
application_type | string (ApplicationType) Value: "web" OPTIONAL. Kind of the application. The default, if omitted, is web. The defined value is web. Web Clients using the OAuth Implicit Grant Type MUST only register URLs using the https scheme as redirect_uris, they MUST NOT use localhost as the hostname. The Authorization Server MUST verify that all the registered redirect_uris conform to these constraints. This prevents sharing a Client ID across different types of Clients. |
client_id | string (ClientId) OPTIONAL. Unique Client Identifier. It MUST NOT be currently valid for any other registered Client. |
client_name | string (ClientName) OPTIONAL. Human-readable string name of the client to be presented to the end-user during authorization. If omitted, iWelcome returns the raw "client_id" as a value for the "client_name". It is RECOMMENDED that clients always send this field. |
client_type | string (ClientType) Enum: "Confidential" "Public" Type of OAuth 2.0 client. Confidential clients can keep their password secret, and are typically web apps or other server-based clients. Public clients run the risk of exposing their password to a host or user agent, such as rich browser applications or desktop clients. If omitted, Confidential type is specified. |
code_challenge_method | string (CodeChallengeMethod) OPTIONAL. String describing if client enforces PKCE (Proof of Key for Code Exchange). Possible values are: none: - PKCE is not enforced upon the client any: - PKCE is enforced but method is selected based on parameter in the request. This mode can be used to be compliant with RFC7636, that indicates "plain" to be the default if method is not provided in request. S256: - PKCE is enforced with 'S256' method If not set, by default it is set to S256. |
contacts | Array of strings (Contact) |
default_scopes | Array of strings (DefaultScope) |
default_max_age | integer (DefaultMaxAge) Default: 1 OPTIONAL. Default Maximum Authentication Age. Specifies that the End-User MUST be actively authenticated if the End-User was authenticated longer ago than the specified number of seconds. The max_age request parameter overrides this default value. If omitted, no default Maximum Authentication Age is specified. |
grant_types | Array of strings (GrantType) Items Enum: "authorization_code" "refresh_token" |
id_token_signed_response_alg | string (IdTokenSignedResponseAlg) OPTIONAL. JWS alg algorithm [JWA] REQUIRED for signing the ID Token issued to this Client. The value none MUST NOT be used as the ID Token alg value unless the Client uses only Response Types that return no ID Token from the Authorization Endpoint (such as when only using the Authorization Code Flow). The default, if omitted, is RS256. The public key for validating the signature is provided by retrieving the JWK Set referenced by the jwks_uri element from OpenID Connect Discovery 1.0 [OpenID.Discovery]. |
logo_uri | string (LogoUri) OPTIONAL. URL that references a logo for the Client application. If present, the server SHOULD display this image to the End-User during approval. The value of this field MUST point to a valid image file. If desired, representation of this Claim in different languages and scripts is represented as described in Section 2.1.: |
jwks | string (Jwks) OPTIONAL. Client's JSON Web Key Set [JWK] document, passed by value. The semantics of the jwks parameter are the same as the jwks_uri parameter, other than that the JWK Set is passed by value, rather than by reference. This parameter is intended only to be used by Clients that, for some reason, are unable to use the jwks_uri parameter, for instance, by native applications that might not have a location to host the contents of the JWK Set. If a Client can use jwks_uri, it MUST NOT use jwks. One significant downside of jwks is that it does not enable key rotation (which jwks_uri does, as described in Section 10 of OpenID Connect Core 1.0 [OpenID.Core]). The jwks_uri and jwks parameters MUST NOT be used together. |
jwks_uri | string (JwksUri) OPTIONAL. URL for the Client's JSON Web Key Set [JWK] document. If the Client signs requests to the Server, it contains the signing key(s) the Server uses to validate signatures from the Client. The JWK Set MAY also contain the Client's encryption keys(s), which are used by the Server to encrypt responses to the Client. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage. Although some algorithms allow the same key to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY be used to provide X.509 representations of keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate. |
response_types | Array of strings (ResponseType) Items Enum: "code" "token" "id_token" "code token" "token id_token" "code id_token" "code token id_token" "none" |
redirect_uris | Array of strings (RedirectUri) |
post_logout_redirect_uris | Array of strings (PostLogoutRedirectUri) |
default_post_logout_redirect_uri | string (DefaultPostLogoutRedirectUri) Indicates where the browser is redirected by default if post_logout_redirect_uri query does not match any of the Post logout redirect uris. iWelcome redirects to the configured default. |
scopes | Array of strings (SingleScope) |
subject_type | string (SubjectType) Value: "public" OPTIONAL. subject_type requested for responses to this Client. The subject_types_supported Discovery parameter contains a list of the supported subject_type values for this server. Valid types include public. |
sector_identifier_uri | string (SectorIdentifierUri) OPTIONAL. URL using the https scheme to be used in calculating Pseudonymous Identifiers by the OP. The URL references a file with a single JSON array of redirect_uri values. Please see Section 5. Providers that use pairwise sub (subject) values SHOULD utilize the sector_identifier_uri value provided in the Subject Identifier calculation for pairwise identifiers. |
token_endpoint_auth_method | string (TokenEndpointAuthMethod) Enum: "client_secret_post" "client_secret_basic" OPTIONAL. Requested Client Authentication method for the Token Endpoint. The options are client_secret_post, client_secret_basic, client_secret_jwt and none, as described in Section 9 of OpenID Connect Core 1.0 [OpenID.Core]. Other authentication methods MAY be defined by extensions. If omitted, the default is client_secret_basic -- the HTTP Basic Authentication Scheme specified in Section 2.3.1 of OAuth 2.0 [RFC6749]. |
{- "application_type": "web",
- "client_id": "string",
- "client_name": "string",
- "client_type": "Confidential",
- "code_challenge_method": "string",
- "contacts": [
- "mary@example.org"
], - "default_scopes": [
- "string"
], - "default_max_age": 1,
- "grant_types": [
- "authorization_code"
], - "id_token_signed_response_alg": "string",
- "logo_uri": "string",
- "jwks": "string",
- "jwks_uri": "string",
- "response_types": [
- "code"
], - "scopes": [
- "authorisation1"
], - "subject_type": "public",
- "sector_identifier_uri": "string",
- "token_endpoint_auth_method": "client_secret_post"
}
{- "application_type": "web",
- "client_id": "string",
- "client_name": "string",
- "client_type": "Confidential",
- "client_secret": "string",
- "code_challenge_method": "string",
- "client_secret_expires_at": 0,
- "contacts": [
- "mary@example.org"
], - "default_scopes": [
- "string"
], - "default_max_age": 1,
- "id_token_signed_response_alg": "string",
- "jwks": "string",
- "jwks_uri": "string",
- "registration_access_token": "string",
- "registration_client_uri": "string",
- "logo_uri": "string",
- "response_types": [
- "code"
], - "scopes": [
- "authorisation1"
], - "subject_type": "public",
- "token_endpoint_auth_method": "client_secret_post"
}
To read the current configuration of the client on the authorization server, the client makes an HTTP GET request to the client configuration endpoint, authenticating with its registration access token.
client_id required | string The client id |
Authorization required | string Bearer |
{- "application_type": "web",
- "client_id": "string",
- "client_name": "string",
- "client_type": "Confidential",
- "client_secret": "string",
- "client_secret_expires_at": 0,
- "code_challenge_method": "string",
- "contacts": [
- "mary@example.org"
], - "default_scopes": [
- "string"
], - "default_max_age": 1,
- "id_token_signed_response_alg": "string",
- "jwks": "string",
- "jwks_uri": "string",
- "response_types": [
- "code"
], - "logo_uri": "string",
- "scopes": [
- "authorisation1"
], - "subject_type": "public",
- "token_endpoint_auth_method": "client_secret_post"
}
To deprovision itself on the authorization server, the client makes an HTTP DELETE request to the client configuration endpoint. This request is authenticated by the registration access token issued to the client
client_id required | string The client id |
Authorization required | string Bearer |
{- "error": "string",
- "error_description": "string"
}
Admin endpoint for deprovisioning a client on the authorization server. An admin makes an HTTP DELETE request to the client configuration endpoint.
Security
The client registration endpoint is protected by a transport-layer security mechanism. The client registration endpoint is a protected endpoint; clients need to provide a valid access_token. The access_token needs to have a scope 'dynamic-client-registration' to be authorised to delete
client_id required | string The client id |
Authorization required | string Bearer |
{- "error": "string",
- "error_description": "string"
}