Skip to main content
Soma supports authenticating users and service accounts with 3 different methods. Authentication is generally used to secure 3 different types of access patterns:
  1. Agents invoking the Soma API’s securely
  2. Users & agents invoking other agents
  3. Users accessing the Soma admin UI and related endpoints
The main reason for configuring an external identity provider is mainly to secure user access patterns to invoking agents or accessing the Soma admin UI. You can configure multiple identity providers for your application. All authentication methods for users will results in issuing an access token & refresh token in the response body as well as set the soma_access_token & soma_refresh_token cookies. This page covers how to configure an external identity provider for user access. Plrease read the following pages for more information about:
Normally we’d recommend setting cookies as HTTP-only, secure and same-site. However, because we are also returning these tokens in the response body, we’ve opted to loosen the security requirements for these cookies in favour of more flexibility.

​
Configuring an external identity provider

You can make use of the following commands to manage your external identity providers: soma auth add oidc <ID> soma auth add oauth <ID> soma auth rm soma auth list The add methods will prompt you for OIDC / Oauth Authorization Code Flow configuration details, including:
  • Client ID
  • Client Secret
  • Redirect URI
  • Scopes
  • Token Endpoint
  • User Info Endpoint
  • Issuer URL
  • JWKS URL
And optionally ask if you would like to configure a way to map scopes, groups to Soma roles & groups. More on that below. Once configured, you can trigger the authentication flow by navigating to the following URL: $SOMA_API_URL/api/identity/v1/auth/authorize/$id where $id is the ID of the configured provider you specified during the add command. The callback URL will return access_token, refresh_token, expires_in in the response body as well as setting soma_access_token & soma_refresh_token cookie which will allow Soma admin UI access (if the user has the correct role).

​
OIDC (OpenID Connect)

OIDC is a standard for authentication that is supported by most modern identity providers. It is a layer of abstraction on top of OAuth 2.0 and is designed to be simpler and more flexible. Configuring an OIDC provider is preffered over Oauth2.0 as we can sync more identity information from the provider, including the user’s email address, groups, etc. This resource provides more information about OIDC.

​
Oauth2.0

Oauth2.0 is a standard for authentication that is supported by most modern identity providers. It is a more complex standard than OIDC and is designed to be more flexible. Soma specifically supports the Authorization Code Flow for Oauth2.0 with optional PKCE support only. This resource provides more information about Oauth2.0.

​
Saml2.0

Saml2.0 is not currently supported by Soma. Open an issue if you would like to see this feature added.

​
STS (Security Token Service)

Soma has a custom STS endpoint which you can invoke in order to swap an external identity provider’s access token for a Soma access token & refresh token. STS can be used to swap OIDC or Oauth2.0 access tokens for a Soma access token & refresh token. The configuration process is very similar to configuring an external identity provider, with the exception that you can specify if the incoming token to validate and swap is present as a request header or cookie. soma sts add from-template will prompt you for the configuration details for the STS endpoint. Once configured, you can invoke the STS endpoint by navigating to the following URL: $SOMA_API_URL/api/identity/v1/sts/$id where $id is the ID of the configured STS provider you specified during the add command.