Skip to main content

SSO with SlashID

Single Sign-On (SSO) is a popular choice amongst both services and users, increasing the service’s confidence in the user’s identity, and reducing the number of login credentials that users have to manage. You can now integrate SSO from third-party identity providers (IdPs) into your frontend with just a few lines of code using the SlashID SDK, and immediately start using additional features from SlashID.

What is SSO and how does it work?​

SSO involves a user granting your service access to their identity information held by a third party IdP, such as Google, Apple, or Facebook. Your service can then retrieve this information and use it to build a user profile, which can be enriched with internal data you collect. This means you can immediately personalize your UX to the user based on the existing information, and you can have greater confidence in the user’s identity. From the user perspective, they use their existing credentials (e.g., Google account), and can continue to log in to your service with those same credentials, reducing friction and minimizing the number of accounts that they must track.

There are multiple standards for implementing SSO. SlashID supports OpenID Connect (OIDC), a standard for authentication built on top of OAuth 2.0, and Security Assertion Markup Language 2.0 (SAML). OIDC is supported by many popular IdPs, while SAML is an older protocol, widely used in the governmental, academic, and enterprise worlds.

In brief, OIDC works as follows:

  • You register your app with the IdP and obtain a client ID and secret
  • When a user wants to use SSO, you call an API exposed by the IdP with your client ID
  • The user is prompted to log in with the IdP
  • Your service receives an authorization code
  • Your service exchanges the authorization code with the IdP for identity and access tokens, authenticated with the client secret

The identity token is a JSON Web Token (JWT) that includes information about the user; the access token can be used subsequently to retrieve user information from the IdP, within the scopes that the user allowed.

SAML works as follows:

  • You register your IdP with your app - that is a SAML Service Provider (SP) - by providing the IdP's metadata
  • You register your app with the IdP by providing the SP's metadata
  • When a user wants to use SSO, you call an API exposed by the IdP with a SAML request
  • The user is prompted to log in with the IdP
  • Your service receives a SAML response signed with the IdP's private key
  • Your service verifies the signature of the SAML response with the IdP's public key that is included in the IdP's metadata
  • The SAML response contains a SAML assertion that includes information about the user

With SlashID, you simply need to provide us with the client ID and secret for an OIDC IdP, or a SAML IdP metadata. You can then call a single method from our SDK; we take care of the rest and return the tokens.

What does SlashID support?​

Social IdPs​

We add support for SSO providers on a regular basis. Currently, SlashID supports SSO via OIDC with the following providers:

  • Google: The required scopes are openid, email, and profile
  • GitHub: The required scopes are read:user and user:email
  • Gitlab: The required scope is read_user
  • Bitbucket: The required scope is account
  • LINE: The required scopes are profile openid and email
  • Facebook: The required scpes are email and public_profile
  • Microsoft: The required scopes are openid, email, profile, and User.Read
  • Azure AD: The required scopes are openid, email profile, and User.Read
  • Okta: The required scopes are openid, email, and profile
  • Apple: The only required scope is email

The OAuth2 callback URL to supply is https://api.slashid.com/oauth/callback

If there is a provider not on this list that you’d like to see, let us know!

Custom IdPs​

We support any SAML 2.0 IdP that supports request through the HTTP Redirect binding, and responses through the HTTP POST binding.

If you need assistance connecting your SlashID organization to a SAML IdP, let us know!

Getting Started​

Before you can start using the SlashID SDK and APIs, you need to sign up and obtain an organization ID and API key, which will be used to authenticate and authorize your API calls.

Setting up providers​

Once you have your organization ID and API key, you are ready to set up the providers you want to use for SSO:

  1. Choose which providers you want to use for SSO. With SlashID you can use multiple providers, as long as they are in the list of supported IdPs above.

  2. Create OAuth credentials for the provider. These will be used during subsequent OIDC authentication flows to authenticate and identify your service. The procedure for creating these differs between providers, and so we have written a guide for each supported provider, linked from the list of providers above.

  3. Once you have your client ID and secret, you need to register these with SlashID using the OAuth credentials API:

    curl -L -X POST 'https://api.slashid.com/organizations/sso/oidc/provider-credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'SlashID-OrgID: <YOUR ORG ID>' \
    -H 'SlashID-API-Key: <YOUR API KEY>' \
    --data-raw '{
      "client_id": "<CLIENT ID>",
      "client_secret": "<CLIENT SECRET>",
      "provider": "<NAME OF THE PROVIDER>",
      "label": "A label for this set of credentials"
    }'

    The client ID, client secret, and provider are required, and the provider must be supported by SlashID. The label is optional, and is intended to help you track your credentials. It is not used by SlashID.

    The client secret and label can be updated later using the API.

    You can register multiple client ID/secret pairs for the same provider, but the client ID must be unique. Note that the SlashID OAuth credentials API will never return the secret, so make sure this is safely stored. You may change the secret stored with /id later.

  4. Repeat steps 2 and 3 for each provider. You are now ready to use the /id SDK to add SSO to your frontend.

Using the SDK for SSO​

To get started with the SDK, we recommend reviewing our SDK documentation.

Implementing SSO is straightforward with the /id SDK. It uses the same simple interface as our other authentication methods, which return a /id token. To initiate SSO, you must provide:

  • Your organization ID
  • The provider chosen by the user
  • The client ID for that provider
  • Optionally, whether to use a popup or redirect for the IdP login; in the latter case, you may also provide a redirect URL, to which the user’s browser will return once the authentication flow is complete. If not provided, the current page’s URL will be used. Popup is the default behavior.
// In a module script
import * as slashid from "@slashid/slashid"
const sid = new slashid.SlashID()

const org_id = "my_org_id" // organization ID, provided on registration with /id
const clientId = "my.client.id" // client ID from the IdP
const provider = "google" // the identity provider to authenticate with

let user = await sid.id(org_id, null, {
  method: "oidc",
  options: {
    client_id: clientId,
    provider: provider,
    ux_mode: "popup",
  },
})

Behind the scenes, the SlashID SDK and backend will carry out the OIDC flow with the IdP using the credentials matching the client ID provided. If you set UX mode to popup, the SDK will return a User object, which is a SlashID token. If set to redirect, the URL specified will be loaded, with an additional URL query parameter appended. You can then use the getUserFromURL SDK method to obtain the User object.

addEventListener("load", async (event) => {
  let user = await sid.getUserFromURL()
  console.log("Retrieved user from URL", { user })
})

If the user was already logged in with the identity provider, they may be immediately authenticated without needing to re-enter credentials.

Using the IdP tokens​

The token container, which can be obtained from the User by accessing the User.tokenContainer property, contains information about the OIDC tokens returned by the identity provider. This information can be used in conjuction with an API key to retrieve the tokens themselves from our API. The token container is a JWT and can be validated using standard JWT libraries. See our guide for a full description of token containers.

{
  // standard JWT claims
  // ...
  // custom SlashID claims
  "user_token": "aaa.bbb.ccc", // signed and encoded SlashID user token
  "oidc_tokens": [
     {
        "authentication_id": "abcdef12-3456-7890-abcd-ef1234567890", // a unique identifier for the authentication that caused these tokens to be issued
        "token_types": ["access", "refresh", "id"], // a list of the token types issued
        "provider": "google", // the IdP used for SSO
        "client_id": "client_id@google", // the client ID used to obtain these tokens
        "oidc_groups": ["admins", "users"] // a list of groups that this user belongs to in the third-party IdP
     }
  ]
}

The OIDC tokens that can be retrieved will include

  • The ID token, a JWT containing information about the user’s identity, based on the information the IdP holds about them
  • The access token, which can be used with the IdP’s APIs to retrieve information about the user
  • Optionally the refresh token, which can be used with the IdP’s APIs to refresh the access token

The token container can be swapped directly for the OIDC tokens it refers to using the get OIDC tokens endpoint. This can be used for the lifetime of the token container. OIDC tokens for a given user can be queried and revoked at any time, even after the token container has expired.

Using the SlashID tokens​

The SlashID token can be used to leverage other SlashID features, such as Direct-ID and secure user attribute storage, through either the SDK or the API.

For example, you can use Direct-ID to create links that land your users on a page pre-authenticated. To do this using the API, you first need to obtain the SlashID user ID from the SlashID token. This can be found in the user_id claim. Then, use the DirectID API to obtain a DirectID value for the user:

curl -L -X POST 'https://api.slashid.com/persons/<USER ID>/direct-id' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'SlashID-OrgID: <YOUR ORG ID>' \
-H 'SlashID-API-Key: <YOUR API KEY>' \
--data-raw '{
  "duration_secs": <HOW LONG IT SHOULD LAST>
}'

The returned string is a Direct-ID that can be embedded in URLs in the challenges parameter. Embed this in a link to your app and use the SDK's getUserFromURL method to have any user land pre-authenticated.

Logging Out​

You can also use the SlashID SDK to log the user out by revoking the IdP tokens, using the SDK’s logout method. This will revoke the embedded tokens and clear any locally stored user data.

user.logout(org_id)