Authentication

Sessions

All authenticated endpoints require a valid session to access. Information on how to obtain and use a session can be found here.

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 Enforce MFA is enabled 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.

SAML

Companies who host their own SAML compatible Identity Provider (IDP) can utilize SAML sign-on for their users to authenticate with Gremlin. SAML provides your organization complete control over the users authentication process and experience. When using SAML, authentication requests are forwarded to your IDP, which performs authentication as your company specifies. Once a user has authenticated, their details such as their email address, are securely delivered to Gremlin and the user is granted access.

SAML configuration can be performed by users with the correct roles in Gremlin Settings on the Security tab.

In order to configure your IDP for SAML please use our Service Provider (SP) metadata, available with the following command:

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

Important SAML Fields

• Assertion Consumer Service URL - https://api.gremlin.com/v1/users/auth/saml/acs: Represents the location your IDP will send the SAML assertion to be validated by our SP.

• Entity ID - http://api.gremlin.com/saml: Unique identifier for the Gremlin SP.

• RelayState - <Company Name>|||https://app.gremlin.com/users/sso/saml/acs|||/: Three parameters seperated by |||. The first being your company name. The second parameter is the app address, where our ACS sends the user once it is done validating. The last is where we send the user once the login is fully complete, the default destination is the home page.

• NameID Format - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress: Specifies the format of the NameID within the SAML assertion. We require a valid email be used.

• Signature Method - http://www.w3.org/2001/04/xmldsig-more#rsa-sha256: What we use for signing our SAML metadata and requests.

• Bindings:

  • AuthnRequest - urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect: Used by our SP to send users to their IDP during SP initiated logins.
  • AuthnResponse - urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST: Used by your IDP when returning the response to our ACS.

SAML Claims

Gremlin supports SAML claims, allowing you to send information during the SAML authentication process about what roles and team memberships a user should possess. Using the information provided in the claim, the user will either be updated if they already exist, or created if they do not yet exist. 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 (required)

Named: company:roles. This can have multiple AttributeValues, each containing a valid role. A list of these valid roles can be found here. Here is an example:

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>

Only one company roles attribute may be present in the claim.

Team Membership Attribute (optional)

There are two different ways to define the team membership attribute depending on your IDP limitations. Only one format may be present in a claim.

• Define a singular Attribute named team:roles. The AttributeValues of this Attribute define the team the user is a member of and the roles they hold. The format for these AttributeValues is team-id;Role,Role ... (ensure there are no spaces) where team-id is the identifier for the team you want the user to be a member of. This identifier can be found by going to the teams configuration page: Here is example of what an Attribute in this format would look like containing two team memberships:

  xml

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

• Define a Attribute per team membership. Each Attribute name is in the format team:team-id. The roles the user posseses for this team are defined in the AttributeValues of this Attribute. Here is an example of two team membership in the form of multiple Attributes:

  xml

  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:e7352a6b-a9a0-513c-81e4-980f680a70c4" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
  6  <saml:AttributeValue xsi:type="xs:string">TEAM_USER</saml:AttributeValue>
  7</saml:Attribute>

Gremlin Okta Integration

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 SAML Setup Example

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.

Add a Relying Party Trust

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

Okta Setup Example

Prerequisites

• Administrator rights to an Okta account for your organization
• Gremlin User that has the role of Company Admin or Company Owner

Creating the Gremlin Portal App in Okta

• Navigate to Applications and select Add Application

  

• Select Create New App

  

• Select Web as the Platform and SAML 2.0 as the Sign on method and hit Create

  

• Name the App name Gremlin and select Next at the bottom of the screen

  

• Fill in the following fields:

  • Single sign on URL - https://api.gremlin.com/v1/users/auth/saml/acs

  • Audience URI (SP Entity ID) - http://api.gremlin.com/saml

  • Default RelayState - <Your Gremlin company name>|||https://app.gremlin.com/users/sso/saml/acs|||/

  • Name ID format - EmailAddress

  • Application username - Email

    

• Save the App. Click on View Setup Instructions

  

• Save the information on this page as this information will be required when setting up the relationship between Gremlin and Okta

  

Connecting Gremlin with Okta

• Navigate to Company Settings -> Security

  

• Click on Enable to enable SAML for the company

• Fill in the following fields with the information provided by Okta:

  • Entity ID - Item titled Identity Provider Issuer

  • URL - Item titled Identity Provider Signle Sign-On URL

  • Set Certificate - Item titled X.509 Certificate

    

• Click Enable to save the configuration. SAML is now enabled for your company