In this guide, we will walk you through the steps required to integrate OpenID Connect with Pure

Introduction 

OpenID Connect (OIDC) is a modern authentication protocol built on top of the OAuth 2.0 framework, designed to streamline the process of verifying user identities while ensuring a secure and user-friendly experience.

Prerequisites

• Administrator or Technical administrator role in Pure
• Pure version 5.30 or later
• Access to the Identity Provider (IdP) you plan to integrate with (e.g., Okta, Azure AD, ADFS, etc.). 

Understanding SSO and OIDC Terminology

When setting up OpenID Connect (OIDC) for single sign-on (SSO) in Pure, it's helpful to know some important terms related to the process. Understanding these terms will make it easier to follow the setup instructions and communicate about how users will log in.

The table below provides simple definitions of key OIDC terms you may encounter. Familiarizing yourself with these terms will give you confidence as you work through the integration process, ultimately helping to create a smoother and more secure login experience for your users.

Step 1 - Configure your IdP

This can be done in many ways depending on your permissions in the IdP and the IdP that you choose to use. 

We recommend to either consult your IT department or the department in charge of Identity management as you might not have the required permission to create or configure this.

Here you will get an overall guide to set up an IdP. 

1. Access your IdP 
   1. Open your IdP's Admin console (e.g., Okta, Azure AD, ADFS)
2. Create a new Client
   1. Select the option to create a new Client or set up SSO with OIDC. You would likely need to provide:
      1. Client ID and Client Secret
      2. Redirect URI which is https://<your hostname>/admin/login/oauth2/code/pure
         1. or use https://<your hostname>/admin/* - if your IdP allows using wildcard
      3. Logout IRL https://<your hostname>/admin/logout
3. Provide Attributes & Claims which you want the IdP to send to Pure 

Otherwise, we would recommend you to find a guide for the IdP you use

Step 2 - Configure Pure

When you have set up the IdP we can go ahead and set up Pure. 

Access your Pure instance and navigate to Administrator→Security→Authentication Configuration

Select OpenID Connect (OAuth2) in the dropdown menu

Input the Issuer location (which should be the URL for the Discovery Document without /.well-known/openid-configuration)

Remember to also input the Client ID and Client secret.

Next up, provide the Username attribute name - This is the value (or attribute) from the IdP which Pure will be using to match on a username e.g. email. 

After that, you would need to add the scopes you need to use to get the username attribute. Example of scopes could be: email and profile.

If you want to add additional scopes, press Add scope and an additional text field will appear. If you added too many scopes and would like to remove one or more, you can do so by pressing Remove.

The scopes which are available for you to use depends on your IdP setup. Consult your IT department or identity team for a full list of scopes and which scopes you would need to use to get the username attribute. 

You are now done and can save your changes by pressing Save. If you are saving your configuration for the first time, you would most likely be met by the prompt asking to confirm your changes. 

When you confirm this, OIDC will now be enabled in Pure, and it will require you to login using your IdP.

Step 4 - Test the SSO Setup

You can test the SSO setup using functionality in the IdP or by accessing https://<your hostname>/admin in an incognito or in-private window.

If you encounter an error, you would need to look at logging in the authentication configuration or see the message from the IdP. 

Advanced settings

The Advanced Setting section ensures that you can input the information needed to get OIDC up and running in the case that Pure do not have access to the discovery document. This section should in any other cases be as shown below: 

FAQ

I get the error: OAuth2: [invalid_token_response] An error occurred while attempting to retrieve the OAuth 2.0 Access Token Response: 401 Unauthorized: [no body] what do I need to do?

This error means that Pure cannot connect to the IdP as it is not authorized to do so. Ensure that the Client ID and Client Secret are correct or that the ClientID have the correct permissions to request on the provided scopes (if required).