Troubleshoot SSO SetupPublic preview

When setting up SSO for your account, you can test your SSO configuration before saving it to prevent misconfiguring SSO and locking out your users. If the test wizard discovers errors, use this guide to understand and resolve them.

Frequently asked questions

• I’m seeing the following error when configuring my application:

  {"error":{"message":"Required field","param":"RelayState"}}

  If you encounter this error when configuring your application, it might indicate that you’re initiating authentication from an identity provider that doesn’t support service provider initiated authentication. We only support identity provider initiated authentication where the identity provider supports service provider initiated authentication as well. It might also be caused by your identity provider not correctly passing the RelayState parameter from the authentication request back with your assertion.

• I’m seeing the following error message when signing into Stripe:

  SAML. Error: Invalid signature type
  

  This error comes from the SAML response not being signed with the proper algorithm; the signature algorithm must be RSA-SHA256, and the digest algorithm must be SHA256. We enforce this for security reasons because SHA-256 is the industry-standard hashing algorithm. SHA-1, the previous standard, is no longer considered safe enough. Refer to your identity provider’s documentation for instructions on how to configure your integration to use SHA-256.

• I’m unable to use the login UI with SSO:

  If you encounter this after configuring SSO, it might indicate that your domain isn’t validated. Make sure the exact domain that you use for your email is verified in the User authentication page.

  If you’ve validated the same domain in multiple accounts with different identity provider configurations for those accounts, we can’t recognize which identity provider to use. In this case, use the following URL with your verified domain to directly sign into your account with SSO. This URL includes the domain and account to authenticate for. Changing the account token at the end of the URL authenticates you against a different account.

  https://dashboard.stripe.com/login/saml_direct/domain/{{YOUR_DOMAIN}}/merchant/{{STRIPE-ACCOUNT-ID}}
  

  If you have another account that isn’t controlled by SSO and haven’t validated your email address for that account, validate your email address and try again.

• I’m seeing an error stating that I need to have a role when trying to sign in:

  If you encounter this after configuring SSO, it most likely indicates that we haven’t received a role for the user in the SAML assertion from the identity provider. Make sure that the assertion being sent to Stripe contains the following attribute.

  <saml2:AttributeStatement>
    <saml2:Attribute Name="Stripe-Role-" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
      <saml2:AttributeValue>role_id
      </saml2:AttributeValue>
    </saml2:Attribute>
  </saml2:AttributeStatement>

  If it does contain this attribute, make sure that you’re sending a valid role_id.

• I’m seeing an error stating that there is something wrong with my CSRF token:

  Make sure that you correctly configured the URLs in your identity provider. Pay specific attention to SSO URL and Audience URI or Entity ID in the documentation and make sure that you enter them correctly in your specific identity provider.

• What if I am locked out of the Stripe Dashboard?

  If only one team member is locked out of the Stripe Dashboard, it usually means their configuration within the identity provider is incorrect. Typically, the issue is that the SAML authentication request doesn’t contain a role for each Stripe account the team member needs to access. The team member should follow up with their identity provider’s administrator to ensure their configuration is correct.

  If all team members are locked out of the Stripe Dashboard, the SSO settings might be misconfigured, or there might be an issue with the identity provider (for example, an outage). In this scenario, the account representative must reach out to Stripe support. We change the account’s SSO configuration from Required to Optional after an identity verification so that the identity provider’s administrator can sign in and fix the configuration.

• Does Stripe support SCIM?

  We don’t support SCIM. If a team member is added to your identity provider, Stripe handles Just-in-Time creation of that team member. This means that when a team member signs in with SSO to the Stripe Dashboard and they don’t have an existing Stripe account, we create one for them for them. When changes are made to a team member’s Dashboard role, Stripe updates the role the next time that team member signs in.

• Can I use SSO to authenticate to the Stripe mobile apps?

  We don’t support SSO through our mobile apps.

• How long is the SSO session length and is it configurable?

  SSO session length is set to 12 hours and isn’t configurable.

• What is the best structure in Okta for supporting multiple Stripe Accounts?

  We recommend using a single Okta app and providing a role attribute for each of your accounts. You can provide different values for different team members on your account by using Okta expressions to access team member profile and group information, and rendering the value dynamically. Learn more about Okta’s expression language.

• Can I continue to manage roles for team members in the Stripe Dashboard?

  The identity provider controls both authentication and authorization to the Stripe Dashboard. We don’t support using the identity provider for authentication and the Dashboard to manage roles. If the role in the Dashboard differs from the role configured by the identity provider, Stripe updates the role in the Dashboard to the role specified in the AttributeStatement when the team member signs in next.

• Can my team members have different roles?

  When signing in, your identity provider must send the correct team member’s role in the AttributeStatement. For a working example, see Okta’s Mapping dynamic team member roles to groups section.

• How can I sign in to multiple accounts using one SAML assertion?

  Send Stripe an assertion from your identity provider with multiple role attributes that contain all the account ids that you want to configure access to. For example:

  <saml2:AttributeStatement>
    <saml2:Attribute Name="Stripe-Role-STRIPE-ACCOUNT-ID1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
      <saml2:AttributeValue>role_id
      </saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute Name="Stripe-Role-STRIPE-ACCOUNT-ID2" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
      <saml2:AttributeValue>role_id
      </saml2:AttributeValue>
    </saml2:Attribute>
  </saml2:AttributeStatement>

• How do I revoke access?

  There are two methods:

  Actively revoke access with an assertion

  Sending Stripe an assertion from your identity provider allows you to grant a team member access to specific Stripe accounts. It also allows you to revoke a team member’s access. Revoke access for a team member by assigning them a role of none for the Stripe account you want to revoke access for. See the page for your identity provider for more information about how to assign roles to team members.

  Example attribute element that revokes access for a team member:

  <saml2:attribute name="Stripe-Role-STRIPE-ACCOUNT-ID" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml2:attributevalue>none
    </saml2:attributevalue>
  </saml2:attribute>

  Caution

  You can’t revoke access for the owner of a Stripe account.

  Passively revoke access with enforcement mode

  When enforcement mode is set to required, only team members who are able to authenticate with your identity provider can access your Stripe account. In required mode, you can revoke a team member’s access to a Stripe account by preventing your identity provider from authenticating them. You can set SSO to required from the User authentication page.

• Why is support for authentication through the Service Provider necessary for Identity Provider-initiated login to work?

  Native IdP-initiated login isn’t supported due to security concerns with the SAML protocol. For example, the SAML assertion can be intercepted in a man-in-the-middle attack, then replayed at another time to gain unauthorized access to an account.

  When team members attempt to sign in using their IdP, Stripe instead treats the request as a Service Provider initiated login and authenticates the team member as expected.

• How do I update my SSO settings when migrating to a new IdP?

  You can update your SSO settings from the User authentication page. When updating SSO settings, we recommend setting the enforcement mode of your account to optional first. This ensures that if there’s an issue, you can still sign in to the Stripe Dashboard with your email and password. If you have a test account, we recommend updating your SSO settings in your test account first and validating the new settings prior to updating your other accounts.

• How do I disable SSO?

  You can set the enforcement mode of your account to Off from the User authentication page to disable SSO. This removes access for any user who can only access the team with SAML. This includes any user who doesn’t have a password set.