相关文章推荐
小百科  ›  OAuth 2.0 / OpenID Connect client registration endpoint | Connect2id
oauth openid
玩篮球的灯泡
1 年前

OAuth 2.0 / OpenID Connect client registration endpoint

1. Clients must be registered

Client applications must be registered with the Connect2id server before they can login end-users with OpenID Connect or request OAuth 2.0 access tokens.

Client registration is specified in:

  • OpenID Connect Dynamic Client Registration 1.0 -- for OpenID Connect relying parties. This spec should be used for almost all cases when you need to register an application with the Connect2id server.

  • OAuth 2.0 Dynamic Client Registration Protocol - RFC 7591 -- for simple OAuth 2.0 clients that don't need OpenID Connect features, e.g. clients using the client credentials grant.

  • OAuth 2.0 Dynamic Client Registration Management Protocol - RFC 7592 -- describes how to read, update or delete a client registration.

    • 2. The client registration endpoint URL

    It is advertised in the registration_endpoint server metadata and has this form:

    [ issuer-url ]/clients

    3. Accessing the client registration endpoint

    The client registration endpoint operates in an open or managed mode, depending on the allow-open-registration configuration setting:

  • Open registration -- Client applications can be freely registered for the commonly used authorization , implicit and refresh_token grants. Open registration is intended for publicly available Connect2id servers configured for automatic OpenID Provider discovery . Note that open registration is limited to the above grants only; an initial access token is required to register a client for other grants, such as password , or to set privileged registration parameters (see next section).

  • Managed registration -- All registration is managed, by an admin or developer portal, or by some other pre-authorisation process, such as software statements (requires plugin ). An initial access token (of type OAuth 2.0 bearer), described in the next section, is required to register a new client.

    • 3.1 Initial access token

    The Connect2id server accepts two types of access tokens to register a new client:

  • The configured master token for unrestricted access to the client registry.

  • An access token issued by the Connect2id server, valid for a single registration only, and having one or more of the following scope values:

  • client-reg -- Permits registration of a client with any grant_types values and the scope parameter set (equivalent to the master access token, or all of the scope values below). This permissive scope value must be used with caution and may be discontinued in future for safety reasons.
  • client-reg:grant:code -- Permits registration of a client with an authorization_code grant type.
  • client-reg:grant:implicit -- Permits registration of a client with an implicit grant type.
  • client-reg:grant:refresh -- Permits registration of a client with a refresh_token type.
  • client-reg:grant:password -- Permits registration of a client with a password grant type.
  • client-reg:grant:client -- Permits registration of a client with a client_credentials grant type.
  • client-reg:grant:jwt -- Permits registration of a client with a urn:ietf:params:oauth:grant-type:jwt-bearer grant type.
  • client-reg:grant:saml -- Permits registration of a client with a urn:ietf:params:oauth:grant-type:saml2-bearer grant type.
  • client-reg:scope -- Permits setting of the scope registration parameter, which may have special meaning for password and other grant handlers. You may append a text string to it to lock down the allowed scope values that the registrant may set. See the example below.
  • client-reg:data -- Permits setting of the custom data registration parameter which may be used to store arbitrary JSON object data for the client.
  • client-reg:set-id -- Permits registration of a client with an identifier specified in a custom preferred_client_id client metadata parameter.
  • client-reg:set-secret -- Permits registration of a client with an secret specified in a custom preferred_client_secret client metadata parameter.
  • client-reg:set-sector-id-urn -- Permits registration of a client with a sector_identifier_uri client metadata parameter that is a URN for a sector ID managed by the OpenID provider.

    • Example scope permitting registration of any grant types: 

    client-reg

    Example scope permitting registration of a client for the authorization_code
and implicit grants only:
    

    client-reg:grant:code client-reg:grant:implicit

    Example scope to permit registration of a client for the password grant and
also allow the registrant to set the openid and email client scopes:
    

    client-reg:grant:password client-reg:scope:openid client-reg:scope:email

    An initial access token can be obtained by making a request to the Connect2id
direct authorisation endpoint.
    

    The initial acess token must be passed with the HTTP request in the
Authorization header:
    

    Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

    3.2 Registration access token
    

    Upon successful registration the client is issued a registration
access token.
This access token can be used by the client to self-manage its registration in
a RESTful manner: read, modify or
delete it.
    

    4. Web API overview
    
Resources

  • /clients [POST] [GET]
    • 

  • /clients/{id}
[GET]
[PUT]
[DELETE]

  • [ Authorization ] Required if open registration is
disabled, or if an initial
access token is needed.
    • 

  • Content-Type Must be set to application/json.
    • 

  • [ Issuer ] The issuer URL for a tenant (in the multi-tenant Connect2id
server edition). The tenant can be alternatively specified by the Tenant-ID
header.
    • 

  • [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server
edition). The tenant can be alternatively specified by the Issuer header.
    • 

    Body:
    

  • A JSON object representation of the client metadata.
    • 

    Success:
    

  • Code: 200
    • 

  • Content-Type: application/json
    • 

  • Body: {object} The client information response.
    • 

    Errors:
    

  • 400 Bad Request
    • 

  • 401 Unauthorized
    • 

  • 500 Internal Server Error
    • 

    Example client registration request:
    

    POST /clients HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json
  "application_type"                : "web",
  "redirect_uris"                   : [ "https://client.example.org/callback",
                                        "https://client.example.org/callback2" ],
  "client_name"                     : "My Cool App",
  "logo_uri"                        : "https://client.example.org/logo.png",
  "token_endpoint_auth_method"      : "client_secret_basic",
  "contacts"                        : [ "[email protected]" ]

    Example client registration response detailing the provisioned identifier,
secret, registration access token and metadata:
    

    HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
  "client_id"                       : "s6BhdRkqt3",
  "client_secret"                   : "JBGuX8sIsPhL2aiHtdo_rb8JIMyTjHkLgfVB_zYf2NQ",
  "client_secret_expires_at"        : 1577858400,
  "registration_access_token"       : "SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0",
  "registration_client_uri"         : "https://c2id.com/clients/s6BhdRkqt3",
  "client_name"                     : "My Cool App",
  "logo_uri"                        : "https://client.example.org/logo.png",
  "contacts"                        : [ "[email protected]" ],
  "application_type"                : "web",
  "grant_types"                     : [ "authorization_code",
                                        "refresh_token" ],
  "response_types"                  : [ "code" ],
  "redirect_uris"                   : [ "https://client.example.org/callback",
                                        "https://client.example.org/callback2" ],
  "token_endpoint_auth_method"      : "client_secret_basic",
  "id_token_signed_response_alg"    : "RS256",
  "subject_type"                    : "public"

    5.1.2 GET
    

    Retrieves the registered OAuth 2.0 clients / OpenID relying parties. In
Connect2id server deployments with very large numbers of clients this can be a
potentially expensive operation and should be used with care.
    

    Header parameters:
    

  • [ Authorization ] The configured master access
token for the client
registry.
    • 

  • [ Issuer ] The issuer URL for a tenant (in the multi-tenant Connect2id
server edition). The tenant can be alternatively specified by the Tenant-ID
header.
    • 

  • [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server
edition). The tenant can be alternatively specified by the Issuer header.
    • 

    Success:
    

  • Code: 200
    • 

  • Content-Type: application/json
    • 

  • Body: {array} JSON array of the registered clients,
empty array if none.
    • 

    Errors:
    

  • 400 Bad Request
    • 

  • 401 Unauthorized
    • 

  • 403 Forbidden
    • 

  • 500 Internal Server Error
    • 

    Example request to get the registered clients:
    

    GET /clients HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

    Example response listing two clients:
    

    HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
    "client_id"                       : "s6BhdRkqt3",
    "client_secret"                   : "JBGuX8sIsPhL2aiHtdo_rb8JIMyTjHkLgfVB_zYf2NQ",
    "client_secret_expires_at"        : 1577858400,
    "registration_access_token"       : "SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0",
    "registration_client_uri"         : "https://c2id.com/clients/s6BhdRkqt3",
    "client_name"                     : "My Cool App",
    "logo_uri"                        : "https://client.example.org/logo.png",
    "contacts"                        : [ "[email protected]" ],
    "application_type"                : "web",
   "grant_types"                      : [ "authorization_code",
                                          "refresh_token" ],
    "response_types"                  : [ "code" ],
    "redirect_uris"                   : [ "https://client.example.org/callback",
                                          "https://client.example.org/callback2" ],
    "token_endpoint_auth_method"      : "client_secret_basic",
    "id_token_signed_response_alg"    : "RS256",
    "subject_type"                    : "public"
    "client_id"                       : "joaix93Kf4",
    "client_secret"                   : "posIjfdOJlejLfdsP0dfk23xkKJwpKfjLkdlslsOz",
    "client_secret_expires_at"        : 1577858400,
    "registration_access_token"       : "POifsadPOIe30xcPJeOjfo2zp_dfsdfoifas_3234",
    "registration_client_uri"         : "https://c2id.com/clients/joaix93Kf4",
    "client_name"                     : "My Test App",
    "logo_uri"                        : "https://app.example.org/logo.png",
    "contacts"                        : [ "[email protected]" ],
    "application_type"                : "web",
    "grant_types"                     : [ "authorization_code",
                                          "refresh_token" ],
    "response_types"                  : [ "code" ],
    "redirect_uris"                   : [ "https://app.example.org/callback" ],
    "token_endpoint_auth_method"      : "client_secret_basic",
    "id_token_signed_response_alg"    : "RS256",
    "subject_type"                    : "public"

    5.2 /clients/{id}
    

    5.2.1 GET
    

    Retrieves an OAuth 2.0 client / OpenID relying party. The Connect2id server
will automatically provision a new client secret if the previous one has
expired.
    

    Note, if the client identifier is invalid, the Connect2id server will
return a 401 Unauthorized status, as mandated by
RFC 7592 for security reasons; privileged
requests with the master bearer access token
will return 404 Not Found.
    

    Path parameters:
    

  • id {string} The client identifier.
    • 

    Header parameters:
    

  • Authorization Must specify the configured master bearer access
token or the
provisioned registration access token.
    • 

  • [ Issuer ] The issuer URL for a tenant (in the multi-tenant Connect2id
server edition). The tenant can be alternatively specified by the Tenant-ID
header.
    • 

  • [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server
edition). The tenant can be alternatively specified by the Issuer header.
    • 

    Success:
    

  • Code: 200
    • 

  • Content-Type: application/json
    • 

  • Body: {object} The client information response.
    • 

    Errors:
    

  • 400 Bad Request
    • 

  • 401 Unauthorized
    • 

  • 404 Not Found
    • 

  • 500 Internal Server Error
    • 

    Example request to retrieve of the registration of client with ID s6BhdRkqt3:
    

    GET /clients/s6BhdRkqt3 HTTP/1.1
Host: c2id.com
Authorization: Bearer SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0

    Example response detailing the registered client information:
    

    HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
  "client_id"                       : "s6BhdRkqt3",
  "client_secret"                   : "JBGuX8sIsPhL2aiHtdo_rb8JIMyTjHkLgfVB_zYf2NQ",
  "client_secret_expires_at"        : 1577858400,
  "registration_access_token"       : "SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0",
  "registration_client_uri"         : "https://c2id.com/clients/s6BhdRkqt3",
  "client_name"                     : "My Cool App",
  "logo_uri"                        : "https://client.example.org/logo.png",
  "contacts"                        : [ "[email protected]" ],
  "application_type"                : "web",
  "grant_types"                     : [ "authorization_code",
                                        "refresh_token" ],
  "response_types"                  : [ "code" ],
  "redirect_uris"                   : [ "https://client.example.org/callback",
                                        "https://client.example.org/callback2" ],
  "token_endpoint_auth_method"      : "client_secret_basic",
  "id_token_signed_response_alg"    : "RS256",
  "subject_type"                    : "public"

    5.2.2 PUT
    

    Modifies an OAuth 2.0 client / OpenID relying party registration. The
Connect2id server will update the registration access
token and if
configured the
client secret as well. When a new client secret is generated the previous one
remains valid for another 30 minutes to enable a seamless rollover.
    

    Note, if the client identifier is invalid, the Connect2id server will
return a 401 Unauthorized status, as mandated by
RFC 7592 for security reasons; privileged
requests with the master bearer access token
will return 404 Not Found.
    

    Path parameters:
    

  • id {string} The client identifier.
    • 

    Header parameters:
    

  • Authorization Must specify the configured master bearer access
token or the
provisioned registration access token.
    • 

  • Content-Type Must be set to application/json.
    • 

  • [ Issuer ] The issuer URL for a tenant (in the multi-tenant Connect2id
server edition). The tenant can be alternatively specified by the Tenant-ID
header.
    • 

  • [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server
edition). The tenant can be alternatively specified by the Issuer header.
    • 

    Body:
    

  • A JSON object representation of the client metadata.
    • 

    Success:
    

  • Code: 200
    • 

  • Content-Type: application/json
    • 

  • Body: {object} The client information response.
    • 

    Errors:
    

  • 400 Bad Request
    • 

  • 401 Unauthorized
    • 

  • 404 Not Found
    • 

  • 500 Internal Server Error
    • 

    Example client update request:
    

    PUT /clients/s6BhdRkqt3 HTTP/1.1
Host: c2id.com
Authorization: Bearer SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0
Content-Type: application/json
  "client_id"                  : "s6BhdRkqt3",
  "application_type"           : "web",
  "redirect_uris"              : [ "https://client.example.org/callback",
                                   "https://client.example.org/callback2" ],
  "client_name"                : "My Cool App",
  "logo_uri"                   : "https://client.example.org/logo.png",
  "policy_uri"                 : "https://client.example.org/privacy-policy",
  "tos_uri"                    : "https://client.example.org/terms-of-service",
  "token_endpoint_auth_method" : "client_secret_basic",
  "contacts"                   : [ "[email protected]" ]

    Example client update response:
    

    HTTP/1.1 200 OK
Content-Type: application/json
  "client_id"                    : "s6BhdRkqt3",
  "client_secret"                : "JBGuX8sIsPhL2aiHtdo_rb8JIMyTjHkLgfVB_zYf2NQ",
  "client_secret_expires_at"     : 1577858400,
  "registration_access_token"    : "SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0",
  "registration_client_uri"      : "https://c2id.com/clients/s6BhdRkqt3",
  "client_name"                  : "My Cool App",
  "logo_uri"                     : "https://client.example.org/logo.png",
  "policy_uri"                   : "https://client.example.org/privacy-policy",
  "tos_uri"                      : "https://client.example.org/terms-of-service",
  "contacts"                     : [ "[email protected]" ],
  "application_type"             : "web",
  "grant_types"                  : [ "authorization_code",
                                     "refresh_token" ],
  "response_types"               : [ "code" ],
  "redirect_uris"                : [ "https://client.example.org/callback",
                                     "https://client.example.org/callback2" ],
  "token_endpoint_auth_method"   : "client_secret_basic",
  "id_token_signed_response_alg" : "RS256",
  "subject_type"                 : "public"

    5.2.3 DELETE
    

    Deletes an OAuth 2.0 client / OpenID relying party registration. All refresh
tokens, access tokens and long-lived (persisted) authorisations for the client
will be revoked / deleted too.
    

    Note, if the client identifier is invalid, the Connect2id server will
return a 401 Unauthorized status, as mandated by
RFC 7592 for security reasons; privileged
requests with the master bearer access token
will return 404 Not Found.
    

    Path parameters:
    

  • id {string} The client identifier.
    • 

    Header parameters:
    

  • Authorization Must specify the configured master bearer access
token or the
provisioned registration access token.
    • 

  • [ Issuer ] The issuer URL for a tenant (in the multi-tenant Connect2id
server edition). The tenant can be alternatively specified by the Tenant-ID
header.
    • 

  • [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server
edition). The tenant can be alternatively specified by the Issuer header.
    • 

    Success:
    

  • Code: 204
    • 

    Errors:
    

  • 400 Bad Request
    • 

  • 401 Unauthorized
    • 

  • 404 Not Found
    • 

  • 500 Internal Server Error
    • 

    Example request to delete the registration of client with ID s6BhdRkqt3:
    

    DELETE /clients/s6BhdRkqt3 HTTP/1.1
Host: c2id.com
Authorization: Bearer SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0

    Example response indicating successful deletion:
    

    HTTP/1.1 204 No Content

    6. Representations
    

    6.1 Client metadata
    

    OpenID Connect client
metadata,
as specified in OpenID Connect Dynamic Client Registration 1.0, section 2.
    

    For simple OAuth 2.0 clients that don’t require OpenID Connect, e.g. clients
using the client credentials grant - OAuth 2.0 client
metadata, as specified in the
OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591), section 2. Note,
the scope parameter, intended to list the allowed scope values for the
client, is supported for OAuth 2.0 client as well as OpenID Connect
registrations.
    

    Client metadata parameters from the following OAuth 2.0 and OpenID Connect
extensions are also supported:
    

  • PKI mutual TLS client authentication (mTLS)
    • 

  • Self-signed mutual TLS client authentication (mTLS)
    • 

  • Mutual TLS client certificate bound access tokens (mTLS)
    • 

  • Pushed authorisation requests (PAR)
    • 

  • JWT-secured authorisation responses (JARM)
    • 

  • OpenID Connect RP-Initiated Logout 1.0
    • 

  • OpenID Connect Front-Channel Logout 1.0
    • 

  • OpenID Connect Back-Channel Logout 1.0
    • 

  • OpenID Connect Federation 1.0
    • 

    In addition to the standard client metadata parameters, the Connect2id server
supports the following optional custom parameters and features:
    

  • [ redirect_uris ] {string array} Supports registration of one or more
redirection URI templates.
    • 

  • [ code_challenge_method ] {string} Sets a code challenge
method (RFC
7636 the client must use. Supported
values are S256 and plain. The default value is none. Since v13.0.
    • 

  • [ data ] {object} Optional custom data, in the form of a JSON object.
    • 

  • [ preferred_client_id ] {string} Sets the client_id for a new
client instead of letting the Connect2id server generate an
identifier. Can be used to import
a client registration from another server.
    • 

  • [ preferred_client_secret ] {string} Sets the client_secret for a new
client or in a client update. Can be used
to import a client
registration from another server.
    • 

  • [ refresh_client_secret = false] {true|false} If true triggers a
generation of a new client_secret when updating a client,
regardless of the expiration status of the current client secret and the configured
op.reg.alwaysRefreshClientSecretOnUpdate
policy. A preferred_client_secret overrides the action of this field.
The default value is false (no new secret generation).
    • 

  • [ sector_identifier_uri ] {string} The standard OpenID Connect parameter
for specifying a sector identifier URI for the relying party can also be a
URN for a sector ID that is managed locally by the OpenID provider. The
expected URN format is urn:c2id:sector_id:<id>. The OpenID provider must
manage the assignment of the URN sector IDs to relying parties prior to
registration and ensure that the ID stays unique for a given OpenID relying
party, unless the sector ID is allowed to be shared by two more relying
parties, typically when those are under single administrative control. To
register URN sector IDs the
op.reg.enableProviderManagedSectorIDs
configuration property must be enabled.
    • 

    Concrete examples can be found in the client registration
guide.
    

    6.2 Client information
    

    Client information response. Consists of the following JSON object members as
well as the JSON object members for the provisioned client
metadata.
    

    JSON object members:
    

  • client_id {string} The provisioned unique client identifier. It is
represented by a secure random alphanumeric string of the configured
length.
    • 

  • [ client_secret ] {string} The client secret, used by confidential
clients to authenticate to the Token Endpoint, as described in the OAuth
2.0 specification. It is
represented by a secure random alphanumeric string of the configured
length. Omitted for
public clients. Also omitted for a GET request when the
secret is stored in a hashed form.
    

    After a client secret update the previous value will remain valid for client
authentication purposes for another 30 minutes, to enable a seamless
rollover.
    • 

  • [ encoded_client_secret ] {string} The encoded (hashed) client secret,
when provided by a client secret codec
plugin.
Since v13.5.
    • 

  • registration_access_token {string} Registration access token that can be
used to query, modify or delete the client's registration. It is
represented by a secure random alphanumeric string of the configured
length.
    • 

  • registration_client_uri {string} The URI of the client's registration. It
is formed by appending the client_id to the client registration endpoint
path.
    • 

  • client_id_issued_at {integer} The client identifier issue timestamp, as
number of seconds since the Unix epoch.
    • 

  • [ client_secret_expires_at ] {integer} Time at which the client_secret
will expire or 0 if it will not expire, according to the configured
client secret lifetime.
Its value is represented as number of seconds since the Unix epoch. Omitted
for public clients.
    • 

    7. Errors
    

    400 Bad Request
    

    Invalid or malformed request.
    

    Example:
    

    HTTP/1.1 400 Bad Request
Content-Type: application/json
  "error"             : "invalid_request",
  "error_description" : "Bad request: Invalid JSON: Unexpected token foo at position 3."

    401 Unauthorized
    

    The request was denied due to an invalid or missing bearer access token. Also
used to indicate that the client resource (registration URI) doesn't exist on
the server.
    

    Example:
    

    HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

    403 Forbidden
    

    The request was denied due to the bearer access token having insufficient
privileges.
    

    Example:
    

    HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope" error_description="Bearer access token has insufficient privileges"

    404 Not Found
    

    The requested resource doesn't exist.
    

    Example:
    

    HTTP/1.1 404 Not Found

    500 Internal Server Error
    

    An internal server error has occurred. Check the Connect2id server logs for
details.
    

    Example:
    

    HTTP/1.1 500 Internal Server Error
     
    推荐文章
    Link管理   ·   51好读   ·   Sov5搜索   ·   小百科
    小百科 - 百科知识指南