Payslip Portal SSO

Owned by Mark Holland (Unlicensed)
Last updated: Sept 03, 2024 by Lewis Allen
6 min read

Description

Use this page to configure Single Sign On (SSO) for the Payslip Portal by entering the company's authentication details.

The following authentication methods are supported:

  1. OAuth 2.0
  2. OpenID Connect

Contents

Usage

SSO removes the need for Payslip Portal users to use a password. Once setup and enabled, the user can login using their company account.

Select Application

The application name for which the SSO Provider information is being configured. It may be InPay or the Payslip Portal.

Metadata

An SSO provider may expose some of their configuration. 


Enter the Metadata URL and click Populate Details to populate the screen with all details made available. If any details are missing, populate the missing details and click Populate Details again to use the missing values to fill in the Authorization Endpoint.


The Populate Certificate button will only populate the certificate (if available). This is useful for OAuth 2.0 providers.


Options

Enable SSO Once this is checked, all payslip portal users with a matching Email Suffix 1 or 2 will be able to login by SSO. If this is checked (even if other details are left blank) employees will have a payslip portal user created on commit where they have an email and it's not currently in use as a payslip portal username. The username will be their email address.

Validate Audience This may be checked if the company wishes to validate the audience. They will need to configure their authentication to provide an audience matching the Payslip Portal URL

Validate Issuer This may be checked if the company wished to validate the issuer. They will need to configure their authentication to provide an issuer matching the Issuer


Validation

Issuer If Validate Issuer is checked, the returned issuer must match this value.


Claims

The payslip portal supports two claims. If none are entered or available, the default identity name will attempt to be matched to the users Payslip Portal Email.

Email Claim The name of the claim that will contain the users Payslip Portal Email. 

Unique Id Claim The name of the claim that will contain a unique identifier for the user. This may also contain the users email or a unique id for the user. It will be used to verify the user in addition to the email after the first login.


Identification

Client Id This allows the company's authentication provider to identify the Payslip Portal and use the correct configuration.

Email Suffix Users matching one of the provided suffixes will login by SSO. This allows left users or users without a company account to login with a password.


Security

Certificate The public certificate used to validated the returned token if Validate Audience or Validate Issuer are checked. Not required for OpenID Connect.

Payslip Portal URL This will be pre populated based on the address used to login to InPay. It's used to populate the Authorization Endpoint and to match the sent audience if Validate Audience is checked.

Log Out URL This URL will be called just before a user logs out to log them out of their company account. Some providers may choose not to support this.

Client Secret  This is the most sensitive piece of data entered on this page. The company must provide this by secure means (E.G. a Client Portal message). Never share this by unsecure means. After populating this field and saving, it's not possible to view the value.


Endpoints

These may be populated from the Metadata URL or entered.

Token Endpoint This will be called with the code returned from the Authorization Endpoint to get the access_token and id_token for the user. If the details match those of the requested user, they will be logged in.

Authorization Endpoint If a username is entered on the login screen of a user that has an email with a suffix matching one of the provided suffixes, they will be sent to this address. They will then log in to their company account and be sent back to InPay with a code.

Display Name

The name of SSO Provider used to identify the provider in case of multiple providers for the same application.

Unique IdP Code

Identifier of the SSO Provider which is unique throughout the application. The distinct IdP Code can be set if IdP Initiated SSO is one of the login choices. After configuring the necessary Single Sign-On (SSO) provider and this field, users can log in by using the provided link.

Sharing Details with Clients and Logging

To easily confirm the correct configuration has been entered with a client. Click the Show Plain Details button.

Once a user is returned from the Authorization Endpoint, the request will be logged showing any issues.


FAQ

Unable to get claims. Ask client to add a claim named UserID to return the users email address.

First try checking Validate Issuer. The claims returned are affected by this setting.

User can't login by SSO

If a user is unable to login by SSO once enabled, first:

  1. Check the log for any error messages to forward to support
  2. Check that the users email address is correct and ends with the text in Email Suffix 1 or Email Suffix 2
  3. Advise the user to register

If they're using Azure (the meta data url will start with login.microsoft...), are still having issues and you're seeing large amounts of text in the log. Ensure the client has added the email claim by sending these instructions:

  • Sign in to the Azure portal.

  • After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  • Search for and select Azure Active Directory.

  • Under Manage, select App registrations.

  • Find the application you want to configure optional claims for in the list and select it.

  • Under Manage, select Token configuration.

  • Select Add optional claim, select the ID token type, select email from the list of claims, and then select Add.

Once they've completed these steps, set the Email Claim and Unique Id Claim in InPay to email

Do you support SAML or SAML 2.0?

No, but most identity providers can support OAuth 2.0 or OpenId Connect.

A search for the name of the identity provider and OpenId Connect will usually give instructions as the first result. e.g:

The client would like some instructions

See Single Sign On, this will be of use even if they are using a different provider.

Message: AADSTS50020: User account 'employeename@company.co.uk' from identity provider 
'live.com' does not exist in tenant 'company name' and cannot access the application 
'identifier'(Payslip Portal) in that tenant. 
The account needs to be added as an external user in the tenant first. 
Sign out and sign in again with a different Azure Active Directory user account.

First confirm the Payslip Portal users saved email address is correct. If so, forward the error messages to the company's internal IT department.

Error message showing token response with no email

This may be that the claim is not being returned. Update the Authorization End Point to request the email scope: scope=openid+email 

The full Authorization End Point would then be similar to https://SSOPROVIDER.COM/oauth2/default/v1/authorize?response_type=code&client_id=000000000000000&scope=openid+email&redirect_uri=https://inpay.es.rsmuk.com/payslipportal4/login.aspx&nonce=&state=

How do I login without entering my username?

Once a user has logged in once, their username will be populated on subsequent attempts (it’s stored in a cookie).

The closest we can get to populating on the first attempt is to put the username into the address E.G. https://inpay.es.rsmuk.com/payslipportal4/?username=support@in-time.co.uk

We don’t currently support IdP-Initiated SSO. This is where they would have an address for their SSO provider E.G. inpay.es.rsmuk.com/payslipportal4/?sso=CompanyName

Unable to aquire token error

If they're using Azure (the meta data url will start with login.microsoft...) then this can mean the client secret is incorrect or expired.

When requesting a new secret, a response like the following can be returned:

Value: <omitted> 
Secret: c55c95b4-056f-4b0a-b6d6-18233b7c76d9 

It is important to note that the value found for the "Value" field is the client secret. The value found for the "Secret" field is a Guid identifier for the secret, and SSO will not work if this is used as that client secret.