External Identity Providers

Overview

Checkout Authentication API (Authentication API) presents a unified interface that seamlessly integrates OAuth 2.0 providers through a redirect chain mechanism. This approach ensures a streamlined and secure authentication flow from your shop, through Authentication API, to various external identity providers (IDP).

By adopting Authentication API, you're not just simplifying authentication; you're embracing an architecture that optimizes security and user experience. This redirect chain method facilitates the authentication process, enhancing your shop's ability to utilize OAuth 2.0 providers without the complexity of individual integrations.

We're committed to supporting you as you navigate the integration of Authentication API into your systems. Our dedicated support team is available to provide guidance, troubleshoot issues, and ensure a seamless implementation experience.

Configuration

How to add external identity providers for your authentication flow:

1. SCAYLE configuration.
2. Identity provider configuration.

SCAYLE configuration

In order to add an external identity provider (IDP), you will need to collect the following information:

Identity provider configuration

When setting up the identity provider, you usually will have the option to configure allowed callback endpoints.

Before you start

Add the following URLs to the list of allowed endpoints:

• Login: https://{{tenant-space}}.auth.scayle.cloud/v1/auth/external/callback
• Logout: https://{{tenant-space}}.auth.scayle.cloud/v1/auth/logout/callback

The Authentication API requires access to:

• Authorization Code
• Refresh Token

Providers

Authentication API is designed to seamlessly integrate with numerous identity providers that adhere to the OAuth 2.0 protocol. This means that your shop can effortlessly connect to a wide array of OAuth 2.0-compatible identity providers through Auth Api's unified interface. Whether it's Google, Facebook, Microsoft, or various other OAuth 2.0-compliant services, Authentication API provides a centralized authentication solution that bridges your shop with a diverse range of identity providers, simplifying the integration process while ensuring security and flexibility.

IDP Login

See how to build your login flow with external identity providers

The login flow consists of following steps:

1. Redirect the user via the Authentication API to the Identity provider.
2. Store the IDP access tokens safely together with the Authentication API access tokens.
3. Create an Authentication API access token, linked to the IDP access token.
4. Redirect the user to a given callbackUrl on the shop.
5. Create access token.

1) Redirect the user via the Authentication API to the Identity provider

Generate a link to the redirect endpoint, including the shopId and a JWT containing the callbackUrl and idpKey. The Authentication API will validate the JWT signature using the shopSecret. Upon successful validation, Authentication API redirects the user to the specified IDP with a 302 Redirect status code.

You can either generate a link, pointing to the Authentication API directly, or you can also provide your own 302 redirect flow upfront, if necessary.

Example:

html

Copy

<a href="https://{{tenant-space}}.auth.scayle.cloud/v1/auth/external/redirect?shopId=...&jwt=...">
    IDP Login
</a>

The JWT payload needs to contain the callbackUrl, the idpKey and the oAuth clientId. See examples below.

Generate the JWT

JavaScriptPHPGoLang

Copy

const jwt = require('jsonwebtoken');

const payload = {
    callbackUrl: 'https://localhost:8080/account-area',
    idpKey: yourCustomIdpIdentifierCode,
    clientId: clientId,
    iat: Math.floor(Date.now() / 1000), // Current timestamp in seconds
    exp: Math.floor(Date.now() / 1000) + (15 * 60) // Expiry: Current time + 15 minutes in seconds
};

const secret = 'yourShopSecretKey';
const token = jwt.sign(payload, secret, { algorithm: 'HS256' });

Refer to the API Specification for further details on Get identity provider callback endpoint.

2) Redirect to the IDP

According to the configuration of the used IDP, the user will be redirected to the IDP Login-Site.

3) Callback to the Authentication API

Once the user authentication was successfully done, the idp redirects the user back to the Authentication API, which will then store the IDP access- and refresh- tokens and create a AuthCode for the shop in order to link them later to a usual Authentication API accessToken.

4) Redirect the user to a given callbackUrl on the shop

The user will be redirect back to your callbackUrl, which you initially defined in the JWT.

The callbackUrl will be extended with additional parameters:

• code - an oauth2 authorization code which you will need to fetch the access- and refresh- tokens of the ongoing authentication flow.
• state - contains the original JWT payload (encoded, see below how to decode).

Decode the callbackUrl parameters

When the redirect to your callbackUrl happens, you will need to fetch the authCode from the request parameters and use it in the next step.

JavaScriptPHPGoLang

Copy

const queryString = require('querystring');

const authCode = req.query.code || '';
const state = req.query.state ? JSON.parse(Buffer.from(req.query.state, 'base64').toString()) : {};

5) Access token creation

Now that you have the authCode, you need to trigger a call to the Authentication API from your backend:

cURL

Copy

curl -X POST --location 'https://{{tenant-space}}.auth.scayle.cloud/v1/oauth/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {base64Encode({client_id}:{client_secret})}' \
--data-raw '{
  "grant_type": "authorization_code",
  "code": "..."
}'

This generates internal Authentication API access and refresh tokens, functioning identically to those used in the standard email and password authentication flow.

The Authentication API will link the IDP access- and refresh- tokens and validate them during the token validation later on.

Logout

See how to build your logout flow with external identity providers

The logout flow consists of:

• Revoking the Authentication API tokens
• Revoking the IDP tokens
• Redirecting the user to a given callbackUrl

Redirect the user to the Authentication API

Generate a link to the logout-redirect endpoint, including the shopId and a JWT containing the callbackUrl and idpKey. The Authentication API will validate the JWT signature using the shopSecret.

You can either generate a link, pointing to the Authentication API directly, or you can also provide your own 302 redirect flow upfront, if necessary.

Example:

http

Copy

<a href="https://{{tenant-space}}.auth.scayle.cloud/v1/auth/logout/redirect?shopId=...&jwt=...">
    Logout
</a>

The JWT payload needs to contain the callbackUrl, and a tokenId.

IDP access token

Get access to the idp access token.

If you need to get the IDP access token, in order to interact with the IDP yourself, you can use the get-token endpoint. The response will then contain a external_token.idp_access_token property which contains the currently valid access token.

If the IDP access tokens expired, the Authentication API will try to refresh it on the fly.