Users and Teams

Authentication

Sessions

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

Note: Sessions last 12 hours until they are considered expired and have to be renewed.

SSO Domains

To enable SSO authentication, enter the domain which users must have an email address associated with.

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:

curl 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 about what roles and team memberships a user possesses during the SAML authentication process. 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

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:

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

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

Team Membership Attribute

Named: team:team-id, 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:

Similiar to the company roles attribute, this attribute can have multiple AttributeValues containing a valid role. Here is an example:

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

Multiple team membership attributes can be present in the claim.

Note: These will overwrite any existing roles and team memberships that the user has. If the user currently has the COMPANY_OWNER role, and the claim only specifies COMPANY_USER, then the user will now have COMPANY_USER as there only role. The same applies for team memberships, if a user belongs to teamA and teamB, yet the claim only has an attribute specifying membership and role information for teamA, then the user will no longer be a member of teamB.