Use OpenID Connect

CyberArk Identity supports OpenID Connect (OIDC), one of the popular authentication protocols, which can be leveraged for federated SSO. This topic provides an overview of OIDC and the OIDC authentication flow: application configuration on the CyberArk Identity Admin portal and user authentication to custom applications using the CyberArk Identity OIDC protocol.

What is OpenID Connect?

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server, and to obtain basic profile information about the end-user in an interoperable and REST-like manner.

The problem

An application that accesses protected resources on behalf of users must be able to verify that users are who they claim to be. One way to enable an application to verify users is by creating a database of usernames and passwords, but using a database is unsatisfactory. It is time-consuming, requires your users to register and remember the usernames and passwords, and needs your client application and server to access them.

The solution

A better solution is to leverage an existing, trustworthy identity provider (IdP) that can authenticate large volumes of users with which your users are already registered. Using an IdP allows your users to log in with existing credentials that they already know and use, while keeping those user credentials secret from your application.

CyberArk Identity supports OIDC, a single sign-on (SSO) standard that enables you to authenticate users using an existing IdP to provide access to client applications; therefore, CyberArk Identity acts as an OpenID Connect provider (OP).

Terminology

The following terms are frequently used in OIDC:

  • Client: An application, such as a website or a mobile application, which accesses the user information and APIs of CyberArk Identity. Note that the client is not the user. The user is the person using the client application.

  • Client ID: The unique identifier that an authorization service issues to identify a client application. The authorization service generates the client ID when the service registers the application. The authorization service uses the client ID and secret in subsequent API requests to ensure that the client can access an online resource and/or a user's information.

  • Client secret: The unique code that an authorization service issues when the service registers the application. You can think of it as the password for the client application. The client secret and the client ID enable the client to access an online resource and/or a user's information. If you are configuring an implementation with the PKCE authorization code flow, you use the code_verifier, code_challenge, and code_challenge_method parameters instead of the client secret in the authorization request.

  • OpenID Connect provider (OP): An OAuth 2.0 authorization server capable of authenticating the end-user and providing claims to a relying party about the authentication event and the end-user. In this case, CyberArk Identity acts as the OpenID Connect provider.

  • Relying party (RP): An OAuth 2.0 client application requiring end-user authentication and claims from an OpenID Connect provider.

  • Single sign-on (SSO): Single sign-on is an authentication scheme that allows users to log in with a single ID to any of several related yet independent websites or mobile applications. Single sign-on enables users to log in once and access services without re-entering authentication factors.

  • Claim: A piece of information about the user.

  • Scope: Scopes provide a way to limit access to APIs and user information.

The OIDC authentication flow

The following diagram illustrates the basic authentication flow. The main actors are:

  • The user (the resource owner)

  • The relying party (the client application that the user is accessing)
  • CyberArk Identity (the OP that acts as an authorization server and the resource server)

In this example:

  1. The user initiates a request through the client application (RP) to start SSO.

  2. The client application redirects the user to the OP, which allows the user to enter credentials.

  3. The redirection information includes the user's application's client ID, client secret, and the location to go to once the user has successfully authenticated (for example, another screen on your website).

  4. Upon successful authentication, the OP returns a temporary authorization code to the client application.

  5. This authorization code is opaque to the client. That is, the client application cannot interpret the authorization code in any way.

  6. The user's credentials are hidden from the application because the application obtains this authorization code instead of direct client credentials.

  7. The client application then sends this temporary authorization code back to the OP. The OP then returns the authorization token and ID token that your client application can use to make subsequent API calls.

OpenID Connect metadata

An OP (for example, CyberArk Identity), also known as an authorization server, provides the following endpoints:

  • Authorization endpoint: The OAuth 2.0 authorization endpoint of an IdP authenticates the user and redirects the user to a redirect URI with an authorization code. The client redirects the user to this endpoint to authenticate and authorize the user.

  • Token endpoint: The endpoint authenticates a client application and allows it to exchange an access code for the token.

  • Userinfo endpoint: The client can use this endpoint to get information about a user, once they are authenticated. This information includes whatever information the user shares in their user configuration.

  • end_session_endpoint: The RP requests CyberArk Identity to log the user out by redirecting the user agent to the end_session endpoint. This URL is obtained via the end_session_endpoint element of the CyberArk Identity metadata URL or it may be learned via other mechanisms.

The RP can request other details, such as claims supported by the OP, ID token signature algorithms, default scopes supported, issuer URL, and so on, using the OP metadata.

The OP metadata is a JSON document containing the OP's endpoint information for a tenant. A client application can use this to configure requests to the OP dynamically. In CyberArk Identity, you can request the OP metadata using <tenant_url>/<application_id>/.well-known/openid-configuration.

You can also use the /OAuth2/GetMeta API to get the metadata of the application.