External Identity Providers

Overview

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

By adopting Auth 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 OAuth2 providers without the complexity of individual integrations.

We're committed to supporting you as you navigate the integration of Auth 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:

SCAYLE configuration.
Identity provider configuration.

SCAYLE configuration

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

`key`	an identifier code for this configuration
`client_id`	the client-id which the Auth Api should use when communicating with the provider
`client_secret`	the client-secret which the Auth Api should use when communicating with the provider
`idp_base_url`	the provider base url used for redirects and api calls, beginning with `https://`, no trailing slash
`scopes`	a list of scopes, which should be requested when logging in a user (optional)
`reference_key_mapping_key`	name of the field which should be used to fetch a referenceKey per user (optional)

SCAYLE will activate this feature for you with the provided configuration. Please contact your SCAYLE Account Manager for further 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 Auth API requires access to:

Authorization Code
Refresh Token

If your provider does not offer configurations for this, you can safely ignore this part.

Providers

Auth Api is designed to seamlessly integrate with numerous identity providers that adhere to the OAuth2 protocol. This means that your shop can effortlessly connect to a wide array of OAuth2-compatible identity providers through Auth Api's unified interface. Whether it's Google, Facebook, Microsoft, or various other OAuth2-compliant services, Auth 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.

Providers you can integrate

37Signals

Acclaim

Admitad

AngelList

AppNet

Apple

ArcGIS

Asana

Atlassian

Auth0

Authentik

Autodesk APS

Aweber

Battlenet

Binance

Bitbucket

Bitly

Bitrix24

Buffer

CampaignMonitor

Cheddar

ClaveUnica

Cognito

Coinbase

ConstantContact

Coursera

Dailymotion

Dataporten

Deezer

Deviantart

DigitalOcean

Discogs

Discord

Disqus

Douban

Dribbble

Dropbox

Envato

Etsy

Eventbrite

Eveonline

EyeEm

Fablabs

Facebook

Fitbit

Flattr

Flexkids

Flickr

Foursquare

FranceConnect

FusionAuth

GarminConnect

GettyImages

GitHub

GitLab

Gitea

Gitee

Goodreads

Google

GovBR

Gumroad

Harvest

HeadHunter

Heroku

HubSpot

Human API

IFSP

Imgur

Instagram

Instagram Basic

Intercom

Kakao

Keycloak

LaravelPassport

Lichess

Life Science Login

Line

MailChimp

Mailru

MakerLog

Mattermost

MediaCube

Medium

Meetup

MercadoLibre

Microsoft

Microsoft Azure

Minecraft

Mixcloud

MoiKrug

Mollie

Monday

Monzo

Naver

Netlify

Notion

OAuthgen

OSChina

Odnoklassniki

Okta

Patreon

PayPal

PayPalSandbox

Paymill

PeeringDB

Pipedrive

Pixnet

Planning Center

Podio

Procore

ProductHunt

ProjectV

Pushbullet

QuickBooks

Readability

Redbooth

RunKeeper

SURFconext

Sage

SalesForce

Saml2

SciStarter

SharePoint

Shopify

Smashcast

Snapchat

SoundCloud

Spotify

StackExchange

Starling

Steam

Steem

StockTwits

Strava

StreamElements

Streamlabs

Stripe

SuperOffice

TVShowTime

Teamleader

Teamweek

TikTok

Todoist

Trakt

Trello

Tumblr

Twitch

Twitter

USOS

Uber

Unsplash

Untappd

VATSIM

Venmo

Vercel

VersionOne

Vimeo

WHMCS

WeChat Service Account

WeChat Web

Webex

Weibo

Weixin

Weixin Web

Withings

WordPress

Worldcoin

Xero

Xing

Yahoo

Yammer

Yandex

YouTube

Zalo

Zendesk

Zoho

Zoom

pr0gramm

See how to build your login flow with external identity providers

The login flow consists of following steps:

Redirect the user via the Auth API to the Identity provider.
Store the IDP access tokens safely together with the Auth API access tokens.
Create an Auth API access token, linked to the IDP access token.
Redirect the user to a given callbackUrl on the shop.
Create access token.

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

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

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

Example:

<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

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' });

yourCustomIdpIdentifierCode needs to be replaced with the key which was used for the identity provider configuration.

clientId needs to be replaced with the client-id you have from the initial api client setup.

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 AuthApi

Once the user authentication was successfully done, the idp redirects the user back to the Auth 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 Auth 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.

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 Auth API from your backend:

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 Auth API access and refresh tokens, functioning identically to those used in the standard email and password authentication flow.

The Auth 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 Auth API tokens
Revoking the IDP tokens
Redirecting the user to a given callbackUrl

Redirect the user to the Auth API

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

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

Example:

<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.

The Access Token ID is not the same as the Access Token itself. If you want to revoke a token you received from the login or register endpoints, you can get the Access Token ID by decoding the Access Token's JWT payload and extract the jti property, which is the ID.

The user will then be redirected back to your callbackUrl.

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 Auth API will try to refresh it on the fly.