Single Sign-On

Scope of Functionality

Single Sign-On is able to manage:

  • Socotra Users and their access to the Socotra UI

  • Machine-based Clients for direct access to the Socotra API, both standard APIs and administrative APIs such as those used for configuration deployment.

Single Sign-On for Configuration Studio and the Socotra Administration UI are not supported.

Important Concepts

Single Sign-On is an alternative to basic authentication, where usernames and password hashes are stored within Socotra. Instead, these credentials are stored within your Identity Provider. When a user wishes to access Socotra with SSO, Socotra will communicate with your Identity Provider using a token supplied by the User. The Identity Provider can indicate whether the user is to be allowed access, and Socotra will use this acknowledgement because Socotra and the Identity Provider will have had a trust relationship previously established.

This protocol allows you to manage access using your own authorization system which can lower administrative effort and provide for user convenience because the login process is usually simplified.

Implementation of Single Sign-On involves the understanding of the following concepts:

  • Identity Providers, which you manage outside of the Socotra environment

  • Socotra Environments, each of which is a distinct service hosted by Socotra

  • Socotra Tenants, of which you control one or more, each of which is housed within a single Environment

  • Namespaces, which are logical groupings of Tenants, used to allow a single SSO User to access multiple Tenants

  • The Socotra SSO Admin Console, a user interface that allows a Namespace Owner to create and manage Users and Clients within a Namespace

  • Users (normally associated with humans) who can be given access to Socotra tenants using the Socotra UI and can manage Namespaces with the Socotra SSO Admin Console.

  • Clients (normally associated with machines), that operate on the Socotra API

These concepts are described in detail in the rest of this feature guide.

Socotra Support

Contact your Socotra Account Representative to get started with Single Sign-On. They will do the following things for you:

  • Help create a trust relationship between your Identity Provider and Socotra SSO

  • Create a Namespace in each of the Socotra environments in which you wish to use Single Sign-On

These tasks are only required to be done once. After this, you will be able to create Users and Clients that can access your Socotra Tenants using SSO.

Identity Providers

The following Identity Providers are supported in this release of Single Sign-On:

  • Azure AD OIDC

  • Auth0 OIDC

  • Google SAML

Other Identity Providers will be supported in upcoming releases. Please contact Socotra Support if you use a provider that is not listed.

Namespaces

Each Socotra environment may contain multiple Namespaces. Namespaces provide role-based access control for data within each environment. An individual Socotra Tenant can exist within, at most, a single Namespace.

Contact your Socotra account representative to create Namespaces for you within your environments or the Socotra Sandbox. For each Namespace, you will be given an account that has the namespace.owner role assigned. You can then manage access to the Namespace using the SSO Admin Console.

Roles

Roles are used to grant access privileges to SSO Users and Clients. There are two different types of Roles: Namespace-Based and Tenant-Based.

Namespace-Based Role

  • Namespace Owner: namespace.owner

Namespace Owners can create Users and Clients and assign roles to them. They can also deploy configurations to tenants in the namespace.

Tenant-Based Roles

  • Employee: account.tenant.employee

  • Read-Only: account.tenant.read.only.user

  • Claims-Only: account.tenant.claims.only.user

The three tenant-based roles correspond to the similar roles used for standard (non-SSO) Socotra accounts.

Note

Some other roles are defined for internal and test purposes. Socotra customers can disregard those roles.

Note

Unlike a User, a Client can only be assigned a single role.

Users

In the Single Sign-On context, a User corresponds to a user profile (for example, “john@mycompany.com”) that is stored within your Identity Provider. Socotra SSO will authorize a user access to a particular environment if SAML or OIDC based trust has been established between your Identity Provider and the Socotra SSO component and the Identify Provider confirms that access should be granted.

Note

User authentication and authorization is based on Authorization Code Flow in the OAuth2 specification, as defined in RFC 6749 - The OAuth 2.0 Authorization Framework.

A User authenticated by your Identity Provider is restricted by Roles assigned to it. These Roles can be modified in the Socotra SSO Admin Console.

In the Socotra UI:

  • If a User has more than one Role assigned, they can switch between these roles using the selector in the top-right corner of the Socotra UI.

  • If a User has no Roles assigned, they will see a default informational page and will not be able to perform any useful actions.

  • A User with a single Namespace or Tenant Role will not see the Role switcher and the sole Role will be implicitly assumed.

  • A User with Tenant-Based Roles will be able to switch to these Roles and perform user-level operations on those tenants.

  • A User with Namespace-Based Roles will be able to switch to the Administration Console for that Namespace.

Clients

A Client is used for programmatic access only.

Note

Client access is based on the Client Credential Flow of the OAuth2 specification, as defined in OAuth 2.0 RFC 6749, section 4.4).

A User or Client with a namespace.owner role can create a Client and provide it Tenant or Namespace roles. Unlike a User, a Client can be assigned only a single Role.

Instead of a traditional username and password, Clients will be assigned a Client ID and Client Secret. These will be used to generate an authorization token, similar to how basic authentication works.

A Client targeting a namespace can create and manage other Clients in that namespace, and create and update tenants in that namespace.

A Client targeting a tenant can perform user-level operations on that tenant, such as policy or claims management.

The Socotra SSO Admin Console

For managing Users and Clients, the Socotra SSO Admin Console is used. It is accessible to Users that are assigned the namespace owner Role.

Each User or Client must be associated with an Id. The form of the id varies by Identity Provider:

  • Azure AD: The user’s Object ID

  • Auth0: The user’s user_id

  • Google: The user’s email address

A User can be assigned multiple Roles in the console.

After a Client is created, the Client Id and Client Secret can be obtained in the Client Details page. Note that:

  • The Client Secret is generated by the server and is displayed only once, although it can be regenerated.

  • Client Roles cannot be changed.

API

The following APIs provide programmatic support for managing Single Sign-On.

Client API

Add a Client
POST /auth/clients
SsoClientResponse
required
clientId string
role string

optional
clientSecret string
clientUuid string
namespace string
Get a Client
GET /auth/clients/{clientUuid}
    Request:
    NamePositionTypeRequired
    clientUuidpathstringrequired
Regenerate the Client Secret
PUT /auth/clients/{clientUuid}/regenerateSecret
    Request:
    NamePositionTypeRequired
    clientUuidpathstringrequired
    Response: string
Remove a Client
DELETE /auth/clients/{clientUuid}
    Request:
    NamePositionTypeRequired
    clientUuidpathstringrequired
    Response: void

Roles API

Get Roles Defined in the Tenant
GET /roles
    Response: RolesResponse
SsoRoleResponse
required
role string

optional
accountType string account.internal | account.tenant.admin | account.tenant.employee | account.tenant.read.only.user | account.tenant.claims.only.user | account.unauthenticated | account.test.tenant.admin | bootstrap
accountTypeDisplayName string
namespace string
namespaceRoleType string  | namespace.owner | namespace.user
namespaceRoleTypeDisplayName string
tenantHostname string

Tenants API

Get a List of Tenants
GET /auth/tenants
SsoTenantResponse
required
locator string
name string
hostname string
timeCreatedInMillisSinceEpoch integer