Server discovery
1. Discovering the server’s endpoints and capabilities
The Connect2id server publishes a JSON document listing its standard endpoints, supported OAuth 2.0 grants, response types, authentication methods and cryptographic algorithms. These details are intended for dynamic clients and application developers to construct requests to the server.
This JSON document, called OpenID Connect provider metadata, has its format specified in the OpenID Connect Discovery 1.0.
OpenID providers publish their metadata at a well-known URL which looks like this:
https://[base-server-url]/.well-known/openid-configuration
The Connect2id server also publishes the same metadata at the well-known URL for plain OAuth 2.0 authorisation servers:
https://[base-server-url]/.well-known/oauth-authorization-server
2. Web API overview
| Resources | |
|---|---|
| Representations | Errors |
3. Resources
3.1 /.well-known/openid-configuration
3.1.1 GET
Retrieves the server’s OpenID provider metadata.
Header parameters:
-
[ Issuer ] The issuer URL when issuer aliases are configured, or 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. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.
Success:
-
Code:
200 -
Content-Type:
application/json -
Body: {object} The OpenID provider metadata.
Errors:
Example request to get the server’s metadata:
GET /.well-known/openid-configuration HTTP/1.1
Host: c2id.com
The response containing a JSON object with the metadata:
HTTP/1.1 200 OK
Content-Type: application/json
{
"issuer" : "https://c2id.com/c2id",
"jwks_uri" : "https://c2id.com/jwks.json",
"registration_endpoint" : "https://c2id.com/clients",
"pushed_authorization_request_endpoint" : "https://c2id.com/par",
"authorization_endpoint" : "https://c2id.com/c2id-login",
"token_endpoint" : "https://c2id.com/token",
"introspection_endpoint" : "https://c2id.com/token/introspect",
"revocation_endpoint" : "https://c2id.com/token/revoke",
"userinfo_endpoint" : "https://c2id.com/userinfo",
"end_session_endpoint" : "https://c2id.com/logout",
"scopes_supported" : [ "openid",
"profile",
"email",
"address",
"phone",
"offline_access" ],
"grant_types_supported" : [ "authorization_code",
"implicit",
"refresh_token",
"password",
"client_credentials",
"urn:ietf:params:oauth:grant-type:jwt-bearer" ],
"response_types_supported" : [ "code",
"token",
"id_token",
"id_token token",
"code id_token",
"code id_token token" ],
"response_modes_supported" : [ "query",
"fragment",
"form_post",
"query.jwt",
"fragment.jwt",
"form_post.jwt",
"jwt",
"json" ],
"prompt_values_supported" : [ "none",
"login",
"consent",
"create" ],
"code_challenge_methods_supported" : [ "plain", "S256" ],
"token_endpoint_auth_methods_supported" : [ "client_secret_basic",
"client_secret_post",
"client_secret_jwt",
"private_key_jwt",
"self_signed_tls_client_auth",
"none" ],
"token_endpoint_auth_signing_alg_values_supported" : [ "HS256",
"HS384",
"HS512",
"RS256",
"RS384",
"RS512",
"PS256",
"PS384",
"PS512",
"ES256",
"ES384",
"ES512" ],
"tls_client_certificate_bound_access_tokens" : true,
"request_parameter_supported" : true,
"request_uri_parameter_supported" : true,
"require_request_uri_registration" : true,
"request_uri_quota" : 10,
"request_object_signing_alg_values_supported" : [ "HS256",
"HS384",
"HS512",
"RS256",
"RS384",
"RS512",
"PS256",
"PS384",
"PS512",
"ES256",
"ES384",
"ES512" ],
"request_object_encryption_alg_values_supported" : [ "RSA-OAEP-256",
"ECDH-ES",
"ECDH-ES+A128KW",
"ECDH-ES+A192KW",
"ECDH-ES+A256KW",
"dir" ],
"request_object_encryption_enc_values_supported" : [ "A128CBC-HS256",
"A192CBC-HS384",
"A256CBC-HS512",
"A128GCM",
"A192GCM",
"A256GCM" ],
"authorization_response_iss_parameter_supported" : true,
"authorization_signing_alg_values_supported" : [ "HS256",
"HS384",
"HS512",
"RS256",
"RS384",
"RS512",
"PS256",
"PS384",
"PS512",
"ES256",
"ES384",
"ES512" ],
"authorization_encryption_alg_values_supported" : [ "RSA-OAEP-256",
"ECDH-ES",
"ECDH-ES+A128KW",
"ECDH-ES+A192KW",
"ECDH-ES+A256KW",
"dir" ],
"authorization_encryption_enc_values_supported" : [ "A128CBC-HS256",
"A192CBC-HS384",
"A256CBC-HS512",
"A128GCM",
"A192GCM",
"A256GCM" ],
"subject_types_supported" : [ "public", "pairwise" ],
"acr_values_supported" : [ "0" ],
"id_token_signing_alg_values_supported" : [ "RS256",
"RS384",
"RS512",
"PS256",
"PS384",
"PS512",
"ES256",
"ES384",
"ES512",
"HS256",
"HS384",
"HS512" ],
"id_token_encryption_alg_values_supported" : [ "RSA-OAEP-256",
"ECDH-ES",
"ECDH-ES+A128KW",
"ECDH-ES+A192KW",
"ECDH-ES+A256KW",
"dir",
"A128KW",
"A192KW",
"A256KW",
"A128GCMKW",
"A192GCMKW",
"A256GCMKW" ],
"id_token_encryption_enc_values_supported" : [ "A128CBC-HS256",
"A192CBC-HS384",
"A256CBC-HS512",
"A128GCM",
"A192GCM",
"A256GCM" ],
"userinfo_signing_alg_values_supported" : [ "RS256",
"RS384",
"RS512",
"PS256",
"PS384",
"PS512",
"ES256",
"ES384",
"ES512",
"HS256",
"HS384",
"HS512" ],
"userinfo_encryption_alg_values_supported" : [ "RSA-OAEP-256",
"ECDH-ES",
"ECDH-ES+A128KW",
"ECDH-ES+A192KW",
"ECDH-ES+A256KW",
"dir",
"A128KW",
"A192KW",
"A256KW",
"A128GCMKW",
"A192GCMKW",
"A256GCMKW" ],
"userinfo_encryption_enc_values_supported" : [ "A128CBC-HS256",
"A192CBC-HS384",
"A256CBC-HS512",
"A128GCM",
"A192GCM",
"A256GCM" ],
"display_values_supported" : [ "page", "popup" ],
"ui_locales_supported" : [ "en" ],
"claim_types_supported" : [ "normal" ],
"claims_supported" : [ "sub",
"iss",
"auth_time",
"acr",
"name",
"given_name",
"family_name",
"nickname",
"email",
"email_verified" ],
"claims_parameter_supported" : true,
"frontchannel_logout_supported" : true,
"frontchannel_logout_session_supported" : true,
"backchannel_logout_supported" : true,
"backchannel_logout_session_supported" : true
}
3.2 /.well-known/oauth-authorization-server
3.2.1 GET
Retrieves the server’s OAuth 2.0 authorisation server metadata.
Header parameters:
-
[ Issuer ] The issuer URL when issuer aliases are configured, or 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 OpenID provider metadata, of which the OAuth 2.0 authorisation server metadata is a superset.
Errors:
4. Representations
4.1 OpenID provider metadata
OpenID provider metadata, as specified in OpenID Connect Discovery 1.0, section 3 and other extending specifications.
May also include custom fields.
JSON object members:
-
issuer {string} The configured issuer URL (server identifier), e.g.
https://c2id.com. -
jwks_uri {string} The public server JWK set URL.
-
registration_endpoint {string} The OAuth 2.0 / OpenID Connect client registration endpoint URL.
-
pushed_authorization_request_endpoint {string} The OAuth 2.0 pushed authorisation request (PAR) endpoint URL.
-
authorization_endpoint {string} The OAuth 2.0 authorisation endpoint URL.
-
token_endpoint {string} The OAuth 2.0 token endpoint URL.
-
introspection_endpoint {string} The OAuth 2.0 token introspection endpoint URL.
-
revocation_endpoint {string} The OAuth 2.0 token revocation endpoint URL.
-
userinfo_endpoint {string} The OpenID Connect UserInfo endpoint URL.
-
[ check_session_iframe ] {string} The OpenID Connect check session iframe URL, omitted if disabled.
-
[ end_session_endpoint ] {string} The OpenID Connect logout endpoint URL, omitted if disabled.
-
grant_types_supported {string array} List of the supported OAuth 2.0 grant types.
-
response_types_supported {string array} List of the supported OAuth 2.0 response_type values.
-
response_modes_supported {string array} List of the supported OAuth 2.0 response_mode values.
-
prompt_values_supported {string array} List of the support OAuth 2.0 authorisation / OpenID authentication request prompt parameter values.
-
code_challenge_methods_supported {string array} List of the supported transformation methods by the authorisation code verifier for Proof Key for Code Exchange (PKCE).
-
[ authorization_response_iss_parameter_supported ] {true|false} Indicates support for the iss authorisation response parameter. If omitted the default value is
false. -
token_endpoint_auth_methods_supported {string array} List of the supported client authentication methods at the OAuth 2.0 token endpoint and other endpoints.
-
[ token_endpoint_auth_signing_alg_values_supported ] {string array} List of the supported JWS algorithms for JWT-based client authentication at the OAuth 2.0 token endpoint and other endpoints, omitted or empty if none.
-
[ request_object_signing_alg_values_supported ] {string array} List of the supported JWS algorithms for JWT-secured authorisation requests (JAR) / OpenID Connect request objects, omitted or empty if none.
-
[ request_object_encryption_alg_values_supported ] {string array} List of the supported JWE encryption algorithms for JWT-secured authorisation requests (JAR) / OpenID Connect request objects, omitted or empty if none.
-
[ request_object_encryption_enc_values_supported ] {string array} List of the supported JWE encryption methods for JWT-secured authorisation requests (JAR) / OpenID Connect request objects, omitted or empty if none.
-
[ authorization_signing_alg_values_supported ] {string array} List of the supported JWS algorithms for signed authorisation responses (JARM).
-
[ authorization_encryption_alg_values_supported ] {string array} List of the supported JWE algorithms for encrypted authorisation responses (JARM).
-
[ authorization_encryption_enc_values_supported ] {string array} List of the supported JWE content encryption methods for encrypted authorisation responses (JARM).
-
id_token_signing_alg_values_supported {string array} List of the supported JWS algorithms for securing the issued ID tokens.
-
[ id_token_encryption_alg_values_supported ] {string array} List of the supported JWE algorithms for securing the issued ID tokens, omitted or empty if none.
-
[ id_token_encryption_enc_values_supported ] {string array} List of the supported JWE encryption methods for securing the issued ID tokens, omitted or empty if none.
-
userinfo_signing_alg_values_supported {string array} List of the supported JWS algorithms for securing the claims returned at the UserInfo endpoint.
-
[ userinfo_encryption_alg_values_supported ] {string array} List of the supported JWE encryption algorithms for securing the claims returned at the UserInfo endpoint, omitted or empty if none.
-
[ userinfo_encryption_enc_values_supported ] {string array} List of the supported JWE encryption methods for securing the claims returned at the UserInfo endpoint, omitted or empty if none.
-
subject_types_supported {string array} List of the supported subject (end-user) identifier types.
-
acr_values_supported {string array} List of the supported Authentication Context Class References (ACRs).
-
display_values_supported {string array} List of the supported display parameters.
-
scopes_supported {string array} List of the supported scope values, omitted if not specified. Certain values may be omitted for privacy reasons.
-
authorization_details_types_supported {string array} List of the supported authorisation details types (RAR), omitted if not specified.
-
claim_types_supported {string array} List of the supported OpenID Connect claim types.
-
claims_supported {string array} List of the supported OpenID Connect claims, omitted if not specified. Certain values may be omitted for privacy reasons.
-
[ claims_locales_supported ] {string array} List of the supported OpenID Connect claims locales, omitted or empty if none.
-
[ ui_locales_supported ] {string array} List of the supported UI locales, omitted or empty if none.
-
claims_parameter_supported {true|false} Indicates support for the claims OpenID authentication request parameter.
-
request_parameter_supported {true|false} Indicates support for the request authorisation request parameter.
-
request_uri_parameter_supported {true|false} Indicates support for the request_uri authorisation request parameter.
-
require_request_uri_registration {true|false} Indicates whether the request_uris must be registered for a client.
-
request_uri_quota {integer} Indicates the maximum number of request_uris that can be registered for a client (custom Connect2id server specific parameter).
-
[ require_pushed_authorization_requests ] {true|false} Indicates whether authorisation requests must be pushed via the PAR endpoint. If omitted the default value is
false. -
[ tls_client_certificate_bound_access_tokens ] {true|false} Indicates support for issuing client X.509 certificate bound access tokens. If omitted the default value is
false. -
[ dpop_signing_alg_values_supported ] {string array} List of the supported JWS algorithms for DPoP proof JWTs, omitted or empty if none.
-
[ native_sso_supported ] {true|false} Indicate support for OpenID Connect Native SSO for Mobile Apps 1.0. If omitted the default value is
false. -
[ frontchannel_logout_supported ] {true|false} Indicates support for OpenID Connect front-channel logout. If omitted the default value is
false. -
[ frontchannel_logout_session_supported ] {true|false} Indicates whether the session ID (
sid) will be included in OpenID Connect front-channel logout notifications. If omitted the default value isfalse. -
[ backchannel_logout_supported ] {true|false} Indicates support for OpenID Connect back-channel logout. If omitted the default value is
false. -
[ backchannel_logout_session_supported ] {true|false} Indicates whether the session ID (
sid) will be included in OpenID Connect back-channel logout notifications. If omitted the default value isfalse. -
[ client_registration_types_supported ] {string list} List of the supported OpenID Connect Federation 1.0 client registration types, omitted if the federation protocol is disabled.
-
[ organization_name ] {string} The name of the organisation in the OpenID Connect Federation 1.0 deployment, omitted if the federation protocol is disabled or a name isn’t specified.
-
[ federation_registration_endpoint ] {string} The OpenID Connect Federation 1.0 registration endpoint URL, omitted if the federation protocol is disabled.
-
[ client_registration_authn_methods_supported ] {object} The supported authentication methods for automatic registration requests in OpenID Connect Federation, omitted if the federation protocol is disabled.
-
[ verified_claims_supported ] {true|false} Indicates support for OpenID Connect for Identity Assurance 1.0. If omitted the default value is
false. -
[ trust_frameworks_supported ] {string array} List of the supported trust frameworks if OpenID Connect for Identity Assurance 1.0 is supported, omitted or empty if none.
-
[ evidence_supported ] {string array} List of the evidence types if OpenID Connect Identity for Assurance 1.0 is supported, omitted or empty if none.
-
[ documents_supported ] {string array} List of the document types if OpenID Connect for Identity Assurance 1.0 is supported, omitted or empty if none.
-
[ id_documents_supported ] {string array} List of the identity document types if OpenID Connect for Identity Assurance 1.0 is supported, omitted or empty if none. Deprecated.
-
[ documents_methods_supported ] {string array} List of the supported coarse identity verification methods for evidences of type document if OpenID Connect for Identity Assurance 1.0 is supported, omitted or empty if none.
-
[ documents_validation_methods_supported ] {string array} List of the supported validation methods for evidences of type document if OpenID Connect for Identity Assurance 1.0 is supported, omitted or empty if none.
-
[ documents_verification_methods_supported ] {string array} List of the supported person verification methods for evidences of type document if OpenID Connect for Identity Assurance 1.0 is supported, omitted or empty if none.
-
[ id_documents_verification_methods_supported ] {string array} List of the identity document verification methods if OpenID Connect for Identity Assurance 1.0 is supported, omitted or empty if none. Deprecated.
-
[ electronic_records_supported ] {string array} List of the supported electronic record types if OpenID Connect for Identity Assurance 1.0 is supported, omitted or empty if none.
-
[ claims_in_verified_claims_supported ] {string array} List of the supported verified claims if OpenID Connect for Identity Assurance 1.0 is supported, omitted or empty if none.
-
[ attachments_supported ] {string array} List of the supported attachment types (embedded, external) if OpenID Connect for Identity Assurance 1.0 is supported, empty if none.
-
[ digest_algorithms_supported ] {string array} List of the the supported digest algorithms for external attachments if OpenID Connect for Identity Assurance 1.0 is supported, omitted or empty if none. The “sha-256” algorithm is always supported for external external attachments.
-
[ op_policy_uri ] {string} The privacy policy document URL, omitted if none.
-
[ op_tos_uri ] {string} The terms of service document URL, omitted if none.
-
[ service_documentation ] {string} The service documentation URL, omitted if none.
5. Errors
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