Skip to main content
Version: 1.0.0

OpenID Connect


LoginID supports OpenID Connect to enable easy integrations that require very little effort. This document explains the supported features, how to get started and how to use it.

Note: the current version is available in our Playground environment!


LoginID supports OpenID Connect as an OpenID Provider (OP) and allows developers to sign up, register applications and leverage FIDO2 based strong authentication within their applications without having to implement support for FIDO2 themselves. Application users register and sign up within the developer's namespace (which is like a tenant ID) during the authentication and authorization flows. Developers will find an overview of application users within the developer dashboard.

Getting started

Leveraging LoginID's support for OpenID Connect starts off with a registration at LoginID's developer dashboard. After that one or multiple applications can be registered and are usable immediately after finishing that short process. Here are a few noteworthy implementation details about supported features:

  • response_types: code
  • grant_types: authorization_code and refresh_token
  • client types: public and confidential
  • scopes: openid, email, offline_access
  • PKCE: required for public clients, using alg=S256
  • claims: sub, email, email_verified
  • token response: access_token, id_token, expires_in, token_type, refresh_token

Registering an application

The first step is to create a developer account here:

  • Developer Dashboard
    • a FIDO2 enabled device is required (i.e.: MacBook with TouchID, Windows Hello, most Smartphones)

Next, register an application:

In the dashboard select Add Application and chose OpenID Connect (OIDC):

  • Application Name: a name of your choice
  • Redirect URIs: the URL to which LoginID redirects users after finishing the authorization_code flow. http may be used for localhost, otherwise https is required
  • Additional Scopes: check the SCOPEs tht will be requested in addition to the default of openid
  • Client Type: for mobile or javascript based applications check Public. For server based web applications check Confidential. Keep it at Automatic if unsure
  • Client Auth Method: for Public clients leave it them all unchecked. For Confidential clients check ..basic... or to get started
  • Links: if available, configure the URLs that should be displayed to users of your app during the authentication - authorization process
  • Enable features: chose as desired. To get started leave the sliders unchanged

Select Create and find an overview of the configuration.

Take note of the following values:

  • Client ID: use that value as the OAuth - OpenID Connect client_id
  • OpenID configuration endpoint: copy and paste that into a browser to get a list of the OpenID configuration including the location of all endpoints. If your application supports that endpoint, use it as openid_configuration_uri
  • Authorization endpoint: use this value or extract it from a response to the endpoint above
  • Redirect URI: your client has to use that value (or one of them if multiple were given) as its redirect_uri when initiating the authorization flow
  • Scopes: these values are the only ones LoginID will grant and only those will be displayed to application users during the authorization flow

Select Next.

If the registered application is of type Confidential an API Credential has to be created. LoginID supports the usage of client_secret, but it has to be a generated JWT.

To get started choose Generate key pair for me. The UI will display a private key in pem format which is your API Credential. Save if at a secure location, it is needed later.

For other cases then evaluating the platform, a key pair should be generated by the developer and only the public key should be shared with LoginID. In that case choose Upload my own public key.

As soon as one is created it may be reused for other applications that get registered. In those cases chose Use existing API credential.

Generating a client_secret

To simplify the process of generating an appropriate key pair and the JWT based client secret we have included instructions in our Tutorial in GitHub.

Please find it here:

The file Tools/ has detailed instructions.

Initializing an authorization flow

Even though OpenID Connect capable clients are configured differently, here are a few hints to get you started more easily:

  • always URLEncode any parameter values:
    • from: https://mydomain/oauth/callback
    • to: https%3A%2F%2Fmydomain%2Foauth%2Fcallback
  • include the same redirect_uri against /authorize and /token
  • separate multiple SCOPE values by a space character [ ]

Initialize the authorization code flow

Typically, a client redirects users to the authorization endpoint like this:

  • 302
  • GET /authorize?
    • client_id={client_id}&
    • redirect_uri={redirect_uri}&
    • scope={scope}&
    • code_challenge={code_challenge_for_PKCE}&
    • code_challenge_method=S256&
    • response_type=code&
    • nonce={nonce}&
    • state={state}

Note: all values in {...} must be URLEncoded!

Once LoginID has handled the user authentication and authorization it will redirect the user back to the client.

The redirect includes either of these parameter combinations:

  • success: {redirect_uri}?code={authorization_code}&state={state}
  • error: {redirect_uri}?error={error}&error_description={error_description}
    • errors include cases where users decided not to authenticate or denied access to requested resources (scopes)

Exchange the authorization code for a token response

After receiving the authorization_code the client has to exchange it for a token response which includes an access_token and an id_token:

  • POST /token
  • Content-Type: application/x-www-form-urlencoded
  • body:
    • client_id={client_id}&
    • client_secret={jwt-based-client-secret}& // this parameter is only required for Confidential clients
    • redirect_uri={redirect_uri}&
    • grant_type=authorization_code&
    • code={authorization_code}&
    • code_verifier={code_verifier_for_PKCE}

Note: all values in {...} must be URLEncoded!

The successful response (status: 200) will contain these values:

"access_token": "an-access-token",
"id_token": "id-token",
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "a-refresh-token"

An error response (status: >= 400) will have this structure:

"error": "error-reason",
"error_description": "error-details"

Processing the token response

Each token of the token response has a specific purpose:

  • access_token: this may be used against LoginID's /userinfo endpoint. However, the retrievable information is also included in the id_token
  • refresh_token: this is issued only if SCOPE=offline_access has been requested. It may be used to refresh an expired access_token
  • id_token: this token is expressed as a JSON Web Token and its content adheres to the OpenID Connect core specification. It represents an authenticated user

TIP: The client SHOULD validate the id_token as follows:

  • verify that aud matches the client_id
  • verify that iss matches issuer as specified in the openid-configuration
  • verify that exp is in the future
  • verify that nonce matches the value that was included in the initial authorization request
  • verify the jwt-signature
    • LoginID's /jwks may be used to retrieve the required public key
    • According to OpenID Connect core, the jwt-signature validation MAY be skipped if the id_token was received via https, directly from the issuer

Use sub of the id_token as user identifier within your application.

Use the id_token as id_token_hint on other platforms that accept a LoginID issued id_token as credential.

More information

To get a better understanding how this feature can be used, please visit our Tutorial which leverages the OpenID Connect integration for demonstration purposes.

We can also be found on GitHub for more code examples.

For specific questions or feedback, please feel free to contact!