Single Sign On on the Paystack Dashboard

Single-Sign-On allows your team manage access to various applications using a single set of credentials through an identity management platform.

The Paystack Dashboard supports Security Assertion Markup Language (SAML) 2.0, an open framework that allows you create users and manage authentication and authorization. Most ID providers also support SAML e.g. Okta, Auth0, Entra ID (formerly known as Azure AD).

Paystack supports the following SSO features

• Just-In-Time account creation: Automatically create new Paystack accounts for users without existing access upon their first SSO sign-in.

• Granular Dashboard roles: Assign granular user roles through your IdP.

• Service Provider-initiated SSO: Initiate SSO login directly from Paystack’s login page.

Single-Sign-On is available on-request to Paystack merchants. Contact our support team at support@paystack.com to enable the feature for your business. You will need to provide an existing admin user on your business to serve as the SSO admin.

Once SSO is enabled for your account, your admin can proceed to set it up from your dashboard settings with these steps

• Confirm ownership of the email domain(s) your team uses

• Set up your ID provider to work with Paystack

• Set up your Paystack Dashboard to work with the ID provider

On the Single Sign-On settings page, click on “Add Domain”

Type in the top level domain you want to verify (e.g. test.com)

You’ll receive a unique TXT record to add to your DNS records to verify domain ownership. Copy this TXT record and set it up on your DNS server.

The verification process should complete immediately. If the domain can’t be verified immediately, wait 24 hours before you retry verification. You can also remove a domain if you choose to.

⚠️ Important to note: You must have at least one verified domain for SSO to remain active on your business.

If the domain is invalid, you’ll will get an error message immediately.

Your admin will need to set up the Paystack dashboard as a service or application on your Identity Provider. This represents the relationship between your provider and Paystack.

• Single Sign On URL or - This value for Paystack is https://api.paystack.co/login/sso/acs.

• Audience URL or Entity ID - An identifier for the Paystack Dashboard within the ID provider. This value for Paystack is https://api.paystack.co/login/sso/metadata.

• Name ID - The identifier that team members have to provide when logging in from the ID Provider’s interface. The value for Paystack is EmailAddress.

You can also find the values above when you click on “Manage SAML” from your SSO settings page.

• Security settings - The types of algorithms that will be used to encrypt and sign authentication messages. On your ID Provider, the Signature Algorithm should be RSA-SHA256 and Digest Algorithm should be SHA256

You can give your users access to the Paystack dashboard from your Identity Provider without inviting them to your business on Paystack first. They will be granted access to your Dashboard once they try to log in.

While SSO is turned on for your Dashboard, these users can only be managed from your Identity Provider. If SSO is turned off on your Dashboard, you can manage users’ access from the Paystack dashboard.

You will be able to assign the Paystack Application to users from your IDP console after you’ve successfully added Paystack as an application. Navigate to the Paystack Dashboard application in your IdP;

• Create a SAML user attribute scoped to Paystack with data type string or text area.

  Name: ps_integration_roles_json

  Display name: PS Integration Roles JSON

• You’ll have to set an attribute statement on your SSO config that points to the user attribute in the application, so that it is available in the SAML assertion sent by the idP to Paystack backend. Sample attribute statements shown in the image below

• When creating a user, populate the PS Integration Roles JSON attribute with a JSON object of the integration you’re trying to add the user to and the role you want to provision them with. Your integration ID is the number underneath your business name at the top left of the Paystack dashboard. Learn more about Paystack dashboard roles here. You’ll have to repeat this for each user you’re adding to the Paystack application.

{"412325":"admin","101256":"admin"}

• Role Codes: On your Paystack Dashboard, click on “View role codes” to see the codes representing all the available roles on your Paystack business. Copy the role codes into your identity provider when giving access the dashboard.

Once you’ve created the relationship with the Paystack dashboard from your ID provider, you’ll need to provide the relevant parameters from your provider on the Paystack Dashboard. The fields you’ll need from your ID provider are:

• Identity Provider Entity ID - A unique identifier from your identity provider.

• Identity Provider SSO URL - The URL where your dashboard team members are redirected to for them to authenticate

• ID provider certificate - The certificate your ID provider will use to sign SAML assertions.

To upload these fields on Paystack, click on “Manage SAML” on the Single Sign-On settings page.

Once you’ve set up SAML on your business, you can choose how you want users to be able to access your business. There are 2 options

On - Your team must use single sign-on to log in.

Off - Your team can't use single sign-on and must use their email and password, or passkeys.

After you finish configuring SSO, you can inform your users to sign in by selecting “Log in with single sign-on (SSO)” on the Paystack Login page.

⚠️ Important to Note: Your SSO Admin will always be able to log in using either their email address and password, passkeys, or SSO.