OIDC Cloud Integration

Note that this article only applies to the FNZ Studio Cloud offering.

Introduction

This document describes the technical requirements for an integration of a third-party Identity Provider (IDP) with our Platform using OpenID Connect.

As previously mentioned, OpenID Connect is an authentication protocol built on top of OAuth 2.0.

The IDP must support OpenID Connect 1.0. It can be a single sign-on system like Amazon Cognito, Microsoft Active Directory Federation Services (AD FS), Okta, or Keycloak. It can also be a public IDP as they are run by companies like Google, Facebook, Apple, Microsoft, and many more.

FNZ Studio plays the role of a Relying Party (RP), sometimes also called a Service Provider (SP). Other terms used sometimes are Application and Client.

For the purpose of this documentation, an IDP and an installation are expected to be available under the following URLs:

  • IDP: https://idp.bank.com/openid
  • FNZ Studio: https://bank.appway.com

Configuration

FNZ Studio (RP/SP)

The minimal amount of information required by FNZ Studio to set up the integration is the following:

  • Issuer URL, for example https://idp.bank.com/openid
  • Client ID, for example appway-cloud
  • Client Secret
  • Name of JWT claim holding the username in the ID Token, for example preferred_username
  • URL of the IDP's Logout Endpoint, including all required parameters

The Issuer URL is the base URL of the IDP. The sign-in page and other endpoints are usually available at subpaths of this URL.

Client ID and Client Secret are usually defined/generated by the IDP when the Relying Party (FNZ Studio in this case) is registered as an "App Client" in the IDP.

Additional information which can be specified on FNZ Studio’s side if needed:

  • OpenID Configuration Discovery URL. This URL is usually constructed by appending /.well-known/openid-configuration to the above Issuer URL. However, if an IDP does not follow this convention, this URL can be set explicitly.
  • Additional OAuth scopes to request, for example groups or email. By default, FNZ Studio will only include the mandatory scope openid in authorization requests.
  • Additional parameters to be appended to the Authorization Endpoint URL when redirecting the user to the IDP's sign-in page.
  • Rules for mapping an external username to an FNZ Studio user ID, for example to remove the domain part of an email address.
  • Name of JWT claim holding the list of groups in the ID Token.
  • Rules for mapping an external group name to an FNZ Studio role name, for example to remove an environment-specific prefix. Can also be used to filter the list of groups.

IDP

Most IDPs require a registration of valid redirect URLs for the Relying Party (FNZ Studio in this case).

For a callback URL (redirect URL used after login), append /j_security_check to FNZ Studio’s base URL: https://bank.appway.com/j_security_check

For a sign-out URL (redirect URL after logout), just use FNZ Studio’s base URL: https://bank.appway.com

If the IDP allows to register multiple sign-out URLs, one can also add the main URL for Appway Studio/ FNZ Studio Composition: https://bank.appway.com/admin/

Some IDPs may also allow to register redirect URLs using wildcards: https://bank.appway.com/*

Requirements

Network Access

Both the FNZ Studio server running in the Cloud as well as the end user's web browser must be able to communicate with the IDP over HTTPS. This usually means that the IDP must be accessible through the public Internet or through a VPN connection. When exposing an IDP to the public Internet, IP restrictions and other security features can be used to restrict access to FNZ Studio servers and legitimate end users.

SSL certificates

The IDP must present an SSL certificate that has been signed by a trusted public certificate authority. Self-signed certificates or certificates of enterprise-internal certificate authorities are not supported.

Discovery

At startup, FNZ Studio will send an HTTP GET request to the OpenID Configuration Discovery URL to get information about the IDP. It expects the response to contain at least the following information:

  • authorization_endpoint: URL of the IDP's Authorization Endpoint, used as sign-in page
  • token_endpoint: URL of the IDP's Token Endpoint, used to get an ID Token
  • jwks_uri: URL of the IDP's JSON Web Key Set (JWKS) document, used to get the public keys to validate the signatures of ID Tokens

In addition, if present, the following features must be available:

  • response_types_supported must contain code
  • grant_types_supported must contain authorization_code
  • id_token_signing_alg_values_supported must contain RS256

For more information, see OpenID Provider Metadata in the OpenID Connect Discovery 1.0 specification.

FNZ Studio will also send an HTTP GET request to the JWKS URL (jwks_uri) to get the public keys used to verify the signatures on the ID Tokens (see below).

Both documents (OpenID Configuration and JWKS) will be re-fetched periodically (based on HTTP cache-control headers) to make sure that the most up-to-date configuration and public keys are used.

Example

Google allows Relying Parties to authenticate users using their Google account.

The Issuer URL for Google’s IDP: https://accounts.google.com

The OpenID Configuration is therefore available under the following URL: https://accounts.google.com/.well-known/openid-configuration (link)

The configuration lists the Authorization Endpoint and Token Endpoint URLs: https://accounts.google.com/o/oauth2/v2/authhttps://oauth2.googleapis.com/token

Finally, the configuration also contains the JWKS URL where the public keys are hosted: https://www.googleapis.com/oauth2/v3/certs (link)

RP/SP-initiated vs. IDP-initiated SSO

Users familiar with SAML (Security Assertion Markup Language) may also be familiar with the concept of RP/SP-initiated vs. IDP-initiated SSO or login. The main difference is whether a user first tries to access FNZ Studio (RP/SP-initiated) or the IDP (IDP-initiated). While OpenID Connect does not specify a flow for IDP-initiated SSO, there may be vendors of IDP systems providing custom flows for IDP-initiated SSO.

FNZ Studio only supports RP/SP-initiated SSO.

RP/SP-initiated SSO

The default sign-in process follows these steps:

  1. A user first tries to access FNZ Studio.
  2. FNZ Studio detects that the user has not yet been authenticated.
  3. FNZ Studio redirects the anonymous user to the IDP's sign-in page, also know as the Authorization Endpoint.
Note: If auto-redirect to the IDP is not enabled in FNZ Studio, FNZ Studio will instead render a login page with a button the user has to press to be sent to the IDP.
  1. The IDP authenticates the user, potentially checking multiple factors like username and password, biometrics, tokens, etc.
  2. After successful authentication, the IDP redirects the user back to FNZ Studio, together with an Authorization Code.
  3. FNZ Studio establishes a backend connection to the IDP's Token Endpoint and exchanges the Authorization Code for an ID Token.
  4. FNZ Studio verifies the ID Token by checking whether it is correctly signed by the IDP.
  5. FNZ Studio extracts user information like username and groups from the ID Token.
  6. FNZ Studio grants or denies access to the user based on whether it is authorized.

IDP-initiated SSO

IDP-initiated SSO is not supported by FNZ Studio.

However, an IDP may allow a user to sign in first and then perform a simple redirect of the user to FNZ Studio. An IDP may also present the user a list of applications available to the user (sometimes called "bookmarks"). The user would then proceed to FNZ Studio by clicking on its link. Initially, FNZ Studio will treat the user as unauthenticated, start an RP/SP-initiated login process, and send the user back to the IDP. Given that the user already has an active and authenticated session with the IDP, the IDP should not ask the user for its credentials once more. Instead, the IDP should immediately redirect the user back to FNZ Studio (step 5 in the section above).

For this to work, FNZ Studio has to be configured to auto-redirect the user from its login page to the IDP’s sign-in page (nm.login.openidconnect.autoredirect = true). See the following article for more information.

Authentication Flow

Authentication Flows are the sequence of requests and steps taken by FNZ Studio as RP/SP and the IDP to authenticate a user. For security reasons, FNZ Studio only supports the Authorization Code Flow.

The following Authentication Flows are supported by FNZ Studio:

  • Authorization Code Flow (response_type=code, grant_type=authorization_code)

The following Authentication Flows are not supported by FNZ Studio:

  • Implicit Flow (response_type=id_token token or response_type=id_token)
  • Hybrid Flows

For more information see Authentication using the Authorization Code Flow in the OpenID Connect Core 1.0 specification.

Client Authentication

A Client Authentication method is used by FNZ Studio to authenticate to the IDP when using the Token Endpoint.

The following Client Authentication methods are supported by FNZ Studio:

  • client_secret_basic (default)
  • client_secret_post
  • private_key_jwt
  • none (used if no client secret is configured)

The following client authentication methods are not supported by FNZ Studio:

  • client_secret_jwt

For more information see Client Authentication in the OpenID Connect Core 1.0 specification.

JSON Web Key Set (JWKS)

All ID Tokens must be signed with RSA keys with the algorithm RS256.

The following key types are supported by FNZ Studio:

  • RSA

The following key types are not supported by FNZ Studio:

  • EC

All the JSON Web Keys (JWK) in the key set must contain the following properties:

  • kid: A unique identifier for the key
  • use: What the key is used for. If present, it must be set to "sig" for signature
  • kty: Key type and cryptographic algorithm used. It must be set to "RSA"
  • n: The modulus for the RSA public key
  • e: The exponent for the RSA public key

All other properties like alg, x5u, x5c, or x5t are ignored.

For more information see JSON Web Key (JWK) Format in RFC 7517.

Session Management

FNZ Studio

When an unauthenticated user tries to access FNZ Studio and FNZ Studio has to redirect the user to the IDP (or render the login page), FNZ Studio first stores some data in the user’s session on FNZ Studio side:

  • Information about the original HTTP request like headers, URL path, and parameters. This information is later used to "replay" this request after successful authentication.
  • A random state value used to correlate the response from the IDP with the original request.

By default, sessions in FNZ Studio expire after 30 minutes. If the user does not return from the IDP to FNZ Studio within this time span, the session in FNZ Studio expires and FNZ Studio will reject the authentication response from the IDP. However, FNZ Studio can be configured to immediately re-initiate a new authentication flow.

IDP

There are no special requirements from FNZ Studio’s side on the IDP’s session management. FNZ Studio only interacts with the IDP during authentication of the user. Once FNZ Studio has fetched the ID Token from the IDP, there are no more interactions with the IDP.

However, if the FNZ Studio Solution makes use of the ID Token, an Access Token, and/or a Refresh Token generated by the IDP, the lifetime of these tokens should be configured carefully to match the Solution requirements.

RP/SP-initiated vs. IDP-initiated Logout

FNZ Studio only supports RP/SP-initiated logout where the user starts the logout process in FNZ Studio.

FNZ Studio can redirect the user to the IDP’s Logout Endpoint to invalidate a potential active session the user may still have with the IDP. After this, the user will be redirected back to FNZ Studio.

A central logout process initiated by the IDP is not supported by FNZ Studio.

Resources