OpenID Connect endpoints

Libraries typically offer OIDC auto-discovery capabilities via a standardized endpoint, the ".well-known" discovery. Alternatively, the relevant endpoints can be configured explicitly.

OpenID Connect discovery endpoint

Authorization server offering OpenID Connect compliant endpoints typically offer a discovery endpoint .well-known/openid-configuration. See OpenID Connect Discovery RFC for further details.

Multitenant Access Control offers per-realm well-known endpoints as defined by OpenId Connect for automatic authorization server endpoint discovery. Most libraries are able to read these endpoints to be configured appropriately automatically.

The path of the discovery endpoint is: <URL of Multitenant Access Control>/auth/realms/<tenant name>/.well-known/openid-configuration, e.g. https://portal.bosch-nexeed.com/iam/auth/realms/7311ea8c-5d48-43fe-acf9-980eedf24b6c/.well-known/openid-configuration.

In case you are using BCI Web Core’s Core module, you can load an application’s configuration from the backend to get the URL of Multitenant Access Control.

If you use the custom introspect endpoint of Multitenant Access Control instead of the discovered standardized endpoint, you will get benefits like the inclusion of the Userinfo endpoint information in the response.

OAuth2 / OpenID Connect endpoints enabling authentication and authorization

To integrate Multitenant Access Control, it helps to understand some standard endpoints of OpenID Connect / OAuth2.

Endpoint Description

/auth
(Discovery: authorization_endpoint)

Purpose: start login flow.

The authorization endpoint is the entrypoint for a user login flow. When redirecting the user there or showing it in a popup, the user will be presented with a login form or the flow will return immediately if the user is already logged into a single sign on session.

/token
(Discovery: token_endpoint)

Purpose: request a token.

See also OpenID.net: UserInfo Endpoint

The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User.

Response body example

{
    "sub": "7d71dc3d-49b7-4419-86b1-7a8bb734b8de",
    "preferred_username": "admin",
    "email": "email@example.com",
    "email_verified": false,
    "roles": [
        "urn:macma-application-role:macma:access-manager",
        "urn:macma-application-role:macma:read-acl"
    ],
    "tname": "bci",
    "tid": "12345678-1234-1234-1234-1234567890ab"
}

/introspect
(Discovery: introspection_endpoint)

Purpose: token validation (modified to include /userinfo in response).

The introspection endpoint is an OAuth 2.0 endpoint that takes a parameter representing an OAuth 2.0 token and returns a JSON RFC7159 document representing the meta information surrounding the token, including whether this token is currently active.

Response body example

{
     "jti": "6ed999a8-3a15-4f66-8301-45f2d2df2e80",
    "exp": 1565355379,
    "nbf": 0,
    "iat": 1565355079,
    "aud": [
        "macma",
        "ppm"
    ],
    "active": true,
    "roles": [
        "urn:macma-application-role:macma:access-manager",
        "urn:macma-application-role:macma:read-acl"
    ]
}

Use the custom OpenID Connect Introspect endpoint instead of Keycloak’s endpoint (listed in the discovery document) to get benefits like the inclusion of the Userinfo endpoint response for use cases in the backend.

/logout
(Discovery: end_session_endpoint)

Purpose: Single sign-out / logout.

Single logout / single sign-out functionality at OpenID Provider (OP) if the user’s intention is to log out of the OP as well. According to the specification, the OP should offer the user a choice whether to really log out from the session or not. The choice must be given if no id_token_hint is given. It is thus advisable to do this after local logout to ensure local logout happens for sure.