User Authentication via SAML and Okta

Gremlin supports several different authentication systems, including password-based (default), Google, OAuth, and SAML. Additionally, you can set certain parameters for different systems, such as requiring MFA during password-based login, or requiring a claim be present during SAML logins. This page provides the necessary instructions for setting up different authentication systems.

Configuring Authentication Preferences

Company Admins and Owners can control which authentication methods are enabled for their users via our Authentication Preferences settings under the Security tab. Here you can enable or disable each of our authentication methods—password, Google, OAuth and SAML—and set extra controls for each one.

Authenticating users with multi-factor authentication (MFA)

Users can enable a multi factor authentication for password based logins in Gremlin Company Settings under the Security tab. Currently, Time-based Token (Time-based One Time Passwords, TOTP) MFA is supported. An example of a compatible authenticator is the Google Authenticator, available on the Apple App Store and Google Play.

MFA can be forced for users across the entire company. When MFA Required is enabled via the Authentication Preferences, all users who authenticate without MFA will be provided with a secret key and QR barcode to setup their authenticator. Certain user roles also have the ability to disable MFA for individual users within their company, useful in cases where a user loses their authenticator.

Authenticating users with SAML

Gremlin supports Security Assertion Markup Language (SAML) via a compatible Identity Provider (IDP). When using SAML, Gremlin forwards authentication requests to your IDP, which performs authentication according to your company's specifications. If a user is authenticated successfully, the IDP returns details such as their email address to Gremlin, and they're granted access. Details and authentication requests are delivered securely.

In order to configure SAML in Gremlin, you must have either the Owner or Admin company roles.

Here's an overview of the steps required to authenticate using SAML:

• Gather the Gremlin Service Provider (SP) metadata.
• Gather the fields necessary for configuring SAML.
• Configure SAML claims.
• Integrate with your IDP.

1. Gathering the Gremlin Service Provider (SP) metadata

In order to configure your IDP for SAML, you'll need our Service Provider (SP) metadata. You can retrieve our Service Provider (SP) metadata with the following command:

1curl https://api.gremlin.com/v1/users/auth/saml/metadata

2. Gathering the fields necessary for configuring SAML

The following fields are necessary for configuring your Identity Provider (IDP):

3. Configuring SAML claims

SAML claims let you define the roles and team memberships users should possess when authenticating with Gremlin. Using the information provided in the claim, Gremlin will create the user if they haven't authenticated before, or update them if they have. These claims take the form of an AttributeStatement which is included within the Assertion block that is sent in the SAML Response from your IDP. Within this AttributeStatement are Attributes defining company level roles and team memberships for the user.

Company roles attribute

This determines the Company-level roles that a user has (if any). The attribute name is company:roles. You can only have one company role attribute block in the SAML claim, but the block can have AttributeValues as long as each one contains a valid role.

The valid roles are:

• COMPANY_USER
• COMPANY_COORDINATOR
• COMPANY_ADMIN
• COMPANY_MANAGER
• COMPANY_OWNER

Details on these privileges these roles have can be found here. Here is an example of what an attribute looks like for a user with both COMPANY_OWNER and COMPANY_USER roles:

1<saml:Attribute Name="company:roles" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
2  <saml:AttributeValue xsi:type="xs:string">COMPANY_OWNER</saml:AttributeValue>
3  <saml:AttributeValue xsi:type="xs:string">COMPANY_USER</saml:AttributeValue>
4</saml:Attribute>

Team membership attribute

This determines the Team-level roles that a user has. The valid roles for the team attributes are:

• TEAM_USER
• TEAM_VIEWER
• TEAM_CREDENTIAL_MANAGER
• TEAM_MANAGER

For details on the privileges available for each role, see Role Based Access Control.

There are two different ways to define the team membership attribute depending on your IDP limitations:

• The team roles format (recommended).
• The team membership format.

You can use either format, but you can only use one format in your SAML claim.

Team roles format

The team roles format provides a more compact way of defining per-team roles. This is the recommended format, as long as your IDP supports it. In this format, each AttributeValue defines both the team and the roles the user has for each team. You can define multiple roles using a comma-separated list. You can use either the team name or team ID as the identifier.

For example, here we add a user to two teams. The user will have the following permissions:

• For My Other Team: TEAM_MANAGER and TEAM_USER
• For 6b336d49-e8ce-5a73-976c-39000cf3d1d0: TEAM_USER

1<saml:Attribute Name="team:roles" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
2  <saml:AttributeValue xsi:type="xs:string">My Other Team;TEAM_MANAGER,TEAM_USER</saml:AttributeValue>
3  <saml:AttributeValue xsi:type="xs:string">6b336d49-e8ce-5a73-976c-39000cf3d1d0;TEAM_USER</saml:AttributeValue>
4</saml:Attribute>

You can find the team name and identifier by going to the team's configuration page:

Team memberships format

The team memberships format splits out each team into its own Attribute and defines roles as AttributeValue. It's more verbose than the team roles format, but may be more compatible with certain IDPs.

You define an Attribute per team membership for the user. Each Attribute name is in the format team:teamId or team:teamName. The roles the user possesses for this team are defined in the AttributeValues of this Attribute. Each AttributeValue can contain a singular role, e.g. TEAM_USER, or it can contain a comma-separated list of roles, e.g. TEAM_USER,TEAM_MANAGER.

Here is an example of two team memberships in the form of multiple Attributes. One uses the team:teamId attribute name with one role per AttributeValue and the other uses the team:teamName attribute name with one AttributeValue containing a comma-separated list of roles. Both are valid.

1<saml:Attribute Name="team:6b336d49-e8ce-5a73-976c-39000cf3d1d0" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
2  <saml:AttributeValue xsi:type="xs:string">TEAM_MANAGER</saml:AttributeValue>
3  <saml:AttributeValue xsi:type="xs:string">TEAM_USER</saml:AttributeValue>
4</saml:Attribute>
5<saml:Attribute Name="team:My Other Team" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
6  <saml:AttributeValue xsi:type="xs:string">TEAM_USER,TEAM_MANAGER</saml:AttributeValue>
7</saml:Attribute>

4. Integrating with your SAML IDP

The next step is adding Gremlin as a Service Provider to your Identify Provider (IDP). While there are more IDPs than we can cover in this document, we'll focus on two: Okta and ADFS.

Okta setup example

If you are using Okta as your IDP, you can utilize Gremlin's Okta Integration in Okta's Integration Network. Instructions on how to setup our integration can be found in Okta's SAML documentaion.

ADFS setup example

These instructions are for Active Directory Federation Services (ADFS).

Prerequisites:

• An Active Directory (AD) instance where users have a specified email address.
• A running Microsoft Server with ADFS deployed.
• An SSL certificate to secure your ADFS endpoints.

• Save the Service Provider (SP) metadata as a file. SP metadata is available from the metadata endpoint.
• Open the ADFS management console and select AD FS > Relying Party Trusts. Right click Relying Party Trusts and select Add Relying Party Trust.
• In the Welcome screen select the desired option for Claims aware or Non claims aware. We have selected Claims aware.
• In the Select Data Source screen, choose Import data about the relying party from a file. Enter the path to the file downloaded in step 1. Note: It is possible to enter this information manually, or ask ADFS to retrieve it directly. See ADFS documentation for more information.
• On the Specify Display Name screen enter the desired Display Name for this service as well as any Notes. You can enter anything you wish here.
• In the Choose Access Control Policy screen select the access control policy suitable for your environment. We have chosen to Permit everyone and require MFA.
• In the Ready to Add Trust screen, you can review the configuration and make any necessary changes. For more information about a particular configuration setting please consult the ADFS documentation.
• In the Finish screen you can select Configure claims issuance policy for this application if desired. Click Close.

Authenticating users with OAuth

Gremlin supports OAuth authentication via custom defined OAuth providers.

Configuring an OAuth provider

When configuring an OAuth provider we require the following information:

• Authoriztion URI: Used to authenticate against the OAuth provider. We will redirect the user to this URL when they initate a OAuth login.
• Token URI: Used to exchange an OAuth code, obtained after logging into the OAuth provider, for an access token.
• User Info URI: Used to query for the email of the user..
• Client Id: The public identifier obtained when registering Gremlin with your OAuth provider.
• Client Secret: The secret obtained when registering Gremlin with your OAuth provider.
• Scope (optional): Define what level of access the access token will have that Gremlin obtains during the OAuth login. The default is email. If you change it from the default, the scope provided must be able to read the email of the user.

To configure these settings you can send the following POST request to our API:

1curl -X POST \
2    --header "Content-Type: application/json" \
3    --header "Authorization: $bearertoken" \
4    https://api.gremlin.com/v1/companies/$companyId/oauth/settings \
5    --data '
6    {
7      "authorizationUri": "https://example.com/oauth/authorize",
8      "tokenUri": "https://example.com/oauth/token",
9      "userInfoUri": "https://example.com/user",
10      "clientId": "exampleClientId",
11      "clientSecret": "exampleClientSecret",
12      "scope": "email"
13    }'

Authenticating via OAuth

After configuring your OAuth provider, you are ready to intiate a OAuth login flow.

To illustrate the flow we have provided a commented python script that explains each step of the process. The requests library is a prerequisite for running this script as well as Python 3.

1import requests
2
3COMPANY_NAME = 'Example Company'
4
5"""
6Initiates OAuth login with Gremlin
7We set `allow_redirects=false` here so we can capture
8the response and extract the state cookie
9"""
10login_response = requests.get(
11   f"https://api.gremlin.com/v1/oauth/login?companyName={COMPANY_NAME}",
12   allow_redirects=False
13)
14assert login_response.status_code == 307
15
16"""
17Response is a 307 redirect to your OAuth provider with the URL
18in the Location header as well as the OAuth state cookie.
19This cookie is required to prevent against CSRF attacks,
20additionally it tracks your state as the OAuth flow progresses.
21You need to extract this cookie so it can be used later
22when being redirected back to the Gremlin API.
23"""
24state_cookie = login_response.cookies['oauth_state']
25oauth_provider_login_url = login_response.headers['Location']
26
27assert state_cookie != None
28assert oauth_provider_login_url != None
29
30"""
31This part is implementation specific depending on your OAuth provider.
32Different OAuth providers may require different things when authenticating the user.
33Also for the first time you authenticate to your OAuth provider with Gremlin,
34a browser may be required so that you can grant
35Gremlin access based on the scope we request.
36
37This example is performing a simple POST request to an
38example OAuth provider with the following information:
39
40 - email: Login email for your user
41 - password: Login password for your user
42 - state: Value of the state cookie obtained in the previous step
43 - redirectUri: URL where your provider should redirect you to after authenticating.
44                It should be https://api.gremlin.com/v1/oauth/callback
45 - clientId: Client Id obtained when registering Gremlin with your OAuth provider
46
47The login specific information may vary depending on your OAuth provider,
48but the state, redirectUri and clientId paramaters
49are often required across all types of provider.
50"""
51body = {
52    'email':  'test@example.com',
53    'password': '*********',
54    'state': state_cookie, # obtained in earlier step
55    'redirectUri': 'https://api.gremlin.com/v1/oauth/callback',
56    'clientId': 'exampleClientId'
57}
58
59"""
60Don't follow redirect as we need to add the state cookie to the next request
61"""
62oauth_provider_login_response = requests.post(
63   oauth_provider_login_url,
64   data=body,
65   allow_redirects=False
66)
67
68"""
69You have now successfully authenticted with your OAuth provider,
70now continue the flow by following the redirect your OAuth provider
71created back to Gremlins /oauth/callback endpoint
72"""
73gremlin_callback_url = oauth_provider_login_response.headers['Location']
74assert gremlin_callback_url != None
75
76"""
77Add the state cookie to the request and then follow the redirect
78to Gremlins /oauth/callback endpoint. If the state cookie is not
79added the request will fail. There is a state parameter in the
80redirect URL you are following and it needs to match the
81value in the cookie. This helps prevent CSRF attacks.
82"""
83cookie = {
84    'oauth_state': state_cookie
85}
86gremlin_callback_response = requests.get(
87   gremlin_callback_url,
88   cookies=cookie
89)
90
91"""
92The response from the callback endpoint will contain the `access_token` in JSON
93This is the end of the OAuth specific flow. This `access_token` can
94now be exchanged for a Gremlin session.
95"""
96assert gremlin_callback_response.status_code == 200
97
98access_token = gremlin_callback_response.json()['access_token']
99assert access_token != None
100
101"""
102We now need a valid Gremlin session which can be used to access
103the authenticated portions of our API. Craft a request to /users/auth/sso
104to exchange access_token for a Gremlin session
105"""
106body = {
107    'companyName': COMPANY_NAME,
108    'accessToken': access_token,
109    'provider': 'oauth',
110}
111sso_response = requests.post(
112   f"https://api.gremlin.com/v1/users/auth/sso?getCompanySession=true",
113   data=body
114)
115assert sso_response.status_code == 200
116
117"""
118The response is a JSON representation of the session.
119In this JSON response is the `header` field which contains a
120Bearer token that can be used in the `Authorization` header
121when making requests to the Gremlin API.
122"""
123bearer_token = sso_response.json()['header']
124assert bearer_token != None
125
126"""
127Done!
128"""

If you encounter any errors during this process or have any questions please reach out to support@gremlin.com.

OpenID Connect Claims

Gremlin supports the OpenID Connect extension to OAuth, allowing you to specify roles and team memberships for your user through the form of JSON Web Token claims.

The first claim we require is either the sub or email claim. We look at both when determining the email for the user being authenticated. At least one of these claims must be present and contain a valid email. The sub claim will take priority over the email claim if both are found to be valid emails.

Specifying the role and team memberships for the user are supported via the following two custom claims:

• company_roles: A list of strings, each value is a role that the user will hold at the company level.
• team_roles: A list of strings, each value represents a single team membership the user will have. The team membership is defined in the following format - teamName;Role1,Role2.

Here is an example of what this would look like in the JSON Web Token:

1{
2  "company_roles": ["COMPANY_USER"],
3  "team_roles": ["Team A;TEAM_USER", "Team B;TEAM_MANAGER,TEAM_USER"]
4}

In the above example, the user will be given the Company User role, and will have a membership in Team A with the Team User role and a membership in Team B with the Team User and Team Manager roles.