Introducing OAuth 2.0 Token Exchange and OpenID Connect (OIDC) Support

Introduction

OAuth 2.0 and OpenID Connect are the most popular and important security protocols for modern API connectivity. While there are many ways to implement OAuth 2.0 and OIDC, a key use case for these protocols is to enable service account authorization for APIs and background tasks integrated with third-party Identity Providers (IdPs) for Single Sign-On (SSO). This allows using an IdP such as Microsoft Entra ID, Okta, or Ping Identity as your IdP for background, service account access to Saviynt Identity Cloud APIs. IdP and SSO support have been a popular request to our product team so we are happy to roll this out.

Specifically, this is implemented using industry standards OAuth 2.0 Token Exchange flow (IETF RFC-8693) and the associated OAuth 2.0 Token Introspection API (IETF RFC-7662). The token exchange can be performed submitting an IdP OAuth 2.0 access token or an IdP OIDC ID token to Saviynt Identity Cloud, which will exchange it for a Saviynt OAuth 2.0 access token. Read more below for an overview and in our documentation for "Configuring OAuth 2.0 Token Exchange Authentication".

How it Works

At a high level, OAuth 2.0 Token Exchange works with applications requesting a Saviynt Identity Cloud API Access Token by presenting and IdP issued token, which can be an OAuth 2.0 access token or an OIDC ID token, both issued by the IdP. There are 3 major parts to such an integration, described below.

The diagram below outlines the high-level flow steps. The credentials and URL configuration needs to be done first as descrbed below. Then there is a 3 part flow. The first part of the flow (Steps 1 and 2) with the custom app receiving an IdP access or OIDC ID token is done independently of Saviynt.

Configuring Saviynt Identity Cloud for Token Introspection

To configure Saviynt Identity Cloud, you will need to configure it to call your IdP's IETF RFC-7662 Token Exchange API. This way, when a token exchange request is made to Saviynt Identity Cloud, Saviynt can call your IdP to validate the access or ID token.

Addtionally, any IdP API credentials such as application client ID and client secret, will need to be configured in both your IdP and Saviynt. The following parameters need to be updated in your externalconfig.properties file.

MSOPENID.CLIENTID=<IdP App Client ID for Saviynt>
MSOPENID.CLIENTSECRET= <IdP App Secret for Saviynt>
MSOPENID.INTROSPECTION.URL=<IdP Introspection API>
MSOPENID.USERNAMEINJSON=preferred_username, sub

Making the Token Exchange Request

The Token Exchange request occurs as Steps 3 and 6 in the diagram. It is designed and implemented by Saviynt is as follows. A sucessful reqwuest will return a Saviynt Identity Cloud OAuth 2.0 access token. Behind the scenes, Saviynt Identity cloud is making a Token Introspection API call to your IdP described in the next section.

For the subject_token_type, the following token types are supported:

1. OAuth 2.0 Access Token: urn:ietf:params:oauth:token-type:access_token
2. OpenID Connect ID Token: urn:ietf:params:oauth:token-type:id_token

POST https://<SAVIYNT_HOSTNAME>/ECM/oauth2/token
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=urn:ietf:params:oauth:grant-type:token-exchange& \
subject_token_type=urn:ietf:params:oauth:token-type:access_token& \
subject_token=<IdP OAuth 2.0 access or OIDC ID token for Custom App>

Making the Token Introspection Request

Inline to the Token Exchange Request from your client, Saviynt will make a Token Introspection API request to your IdP to ensure the token is still valid (Steps 4 and 5). It is important to note that this is a live call to your IdP. Your app does not need to make this call. It is made for you by Saviynt.

POST /path/to/introspect HTTP/1.1
Host: <IdP Hostname>
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <IdP access token for Saviynt Identity Cloud>

token=<IdP OAuth 2.0 access or OIDC ID token for Custom App to validate>

The Token Exchange Response

Upon receiving a successful response from the IdP's Token Introspection API endpoint, Saviynt will provide the custom app with an OAuth 2.0 access token to call Saviynt APIs.

Try it Out!

We are very excited about this enhancement and look forward to our customers trying this out. The documentation is available here again. If you have any questions, feel free to post on the Saviynt Forums. And if you have any feature requests for different OAuth 2.0 flows or OpenID Connect capabilities, please post on the Saviynt Ideas Portal.