HomeGuidesRecipesAPI ReferenceChangelog
Treasury Portal Login
Guides
Treasury Portal Login
Start typing to search…

SSO

Single Sign-On (SSO) Integration Guide for the Treasury Portal

Overview

Yellow Card Treasury Portal supports Single Sign-On (SSO) integration with your corporate identity provider, allowing your team to access the portal using their existing corporate credentials. This guide covers the setup process for popular identity providers and configuration requirements.


Supported Protocols

  • OIDC (OpenID Connect) - Recommended for most modern identity providers
  • SAML 2.0 - Traditional enterprise protocol, widely supported

Supported Identity Providers

  • Okta
  • Microsoft Entra ID (formerly Azure AD)
  • Google Workspace
  • Auth0
  • Any SAML 2.0 or OIDC-compliant identity provider

Quick Navigation

📋 Configuration Steps:

🔧 Provider-Specific Setup Guides:

🔒 Important Sections:


Getting Started

Prerequisites

  1. Admin Access: You must have the Admin role on the Treasury Portal
  2. IdP Admin Access: Administrative access to your corporate identity provider
  3. Email Domain: Your organisation must use a consistent email domain (e.g., @yourcompany.com) for all users

Overview of Setup Process

  1. Configure SSO under Account settings in Treasury Portal
  2. Create an application in your identity provider
  3. Configure attribute mappings
  4. Test the connection
  5. Activate SSO for your organisation

Step 1: Configure SSO in Treasury Portal

👤

You must have Admin role access to configure SSO settings.

  1. Log in to the Treasury Portal with your Admin account
  2. Navigate to Account Settings > Security and Controls > Single Sign-On
  3. Click Configure SSO
  4. Choose your protocol (OIDC recommended for most providers)
  5. Enter your identity provider details (covered per-provider below)
  6. Test your connection and activate.

Provider-Specific Setup Guides

ℹ️

Note: The configuration values shown here are placeholders. Actual values will be provided on the Treasury Portal configuration interface

Okta

Protocol: OIDC (Recommended) or SAML 2.0

💡

Tip: For Okta, OIDC is recommended as it's more straightforward to configure and provides better error messaging during troubleshooting.


OIDC Setup with Okta

  1. In Okta Admin Console:

    • Navigate to Applications > Applications
    • Click Create App Integration
    • Select OIDC - OpenID Connect
    • Choose Web Application
    • Configure the application:
      • App integration name: "Yellow Card Treasury Portal"
      • Grant type: Authorization Code
      • Sign-in redirect URIs: https://sso.portal.yellowcard.io/oauth2/idpresponse
      • Sign-out redirect URIs: https://portal.yellowcard.io/login
      • Assignments: Assign to appropriate groups/users

  2. In Treasury Portal:

    • Protocol: OIDC
    • Issuer URL: https://yourorg.okta.com (replace with your Okta domain)
    • Client ID: Copy from Okta application settings
    • Client Secret: Copy from Okta application settings

SAML Setup with Okta

  1. In Okta Admin Console:

    • Navigate to Applications > Applications
    • Click Create App Integration
    • Select SAML 2.0
    • Configure the application:
      • App name: "Yellow Card Treasury Portal"
      • Single sign on URL: https://sso.portal.yellowcard.io/saml2/idpresponse
      • Audience URI (SP Entity ID): urn:amazon:cognito:sp:eu-west-2_XgIgQU2Xa
      • Default RelayState: (leave blank)
      • Name ID format: EmailAddress
      • Application username: Email

  2. Attribute Statements (Required):

    NameFormatValue
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressURI Referenceuser.email
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameURI Referenceuser.firstName
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameURI Referenceuser.lastName
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameURI Referenceuser.displayName
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifierURI Referenceuser.login

  3. In Treasury Portal:

    • Protocol: SAML
    • Metadata URL: Copy from Okta application settings (under "Sign On" tab)


Microsoft Entra ID (Formerly Azure AD)

Protocol: OIDC (Recommended) or SAML 2.0


OIDC Setup with Entra ID

  1. In Azure Portal:

    • Navigate to Microsoft Entra ID > App registrations
    • Click New registration
    • Configure:
      • Name: "Yellow Card Treasury Portal"
      • Supported account types: Accounts in this organisational directory only
      • Redirect URI: Web → https://sso.portal.yellowcard.io/oauth2/idpresponse
    • After creation, note the Application (client) ID
    • Go to Certificates & secrets > New client secret
    • Note the secret value (copy immediately)

  2. In Treasury Portal:

    • Protocol: OIDC
    • Issuer URL: https://login.microsoftonline.com/[TENANT_ID]/v2.0 (replace with your tenant ID)
    • Client ID: Application (client) ID from Azure
    • Client Secret: Client secret value from Azure

SAML Setup with Entra ID

  1. In Azure Portal:

    • Navigate to Microsoft Entra ID > Enterprise applications
    • Click New application > Create your own application
    • Choose Integrate any other application you don't find in the gallery
    • Configure Single Sign-On:
      • Identifier (Entity ID): urn:amazon:cognito:sp:eu-west-2_XgIgQU2Xa
      • Reply URL (Assertion Consumer Service URL): https://sso.portal.yellowcard.io/saml2/idpresponse

  2. User Attributes & Claims (Required):

    NameFormatValue
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressURI Referenceuser.mail
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameURI Referenceuser.givenname
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameURI Referenceuser.surname
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameURI Referenceuser.displayName
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifierURI Referenceuser.login

  3. In Treasury Portal:

    • Protocol: SAML
    • Metadata URL: Copy from Azure (SAML-based sign-on section)


Google Workspace

Protocol: OIDC (Recommended) or SAML 2.0

📝

Ensure you have Google Workspace admin privileges to create custom SAML apps or OAuth applications.


OIDC Setup with Google Workspace

  1. In Google Cloud Console:

    • Navigate to APIs & Services > Credentials
    • Click Create Credentials > OAuth 2.0 Client IDs
    • Configure:
      • Application type: Web application
      • Name: "Yellow Card Treasury Portal"
      • Authorized redirect URIs: https://sso.portal.yellowcard.io/oauth2/idpresponse

  2. In Treasury Portal:

    • Protocol: OIDC
    • Issuer URL: https://accounts.google.com
    • Client ID: Copy from Google Cloud Console
    • Client Secret: Copy from Google Cloud Console

SAML Setup with Google Workspace

  1. In Google Admin Console:

    • Navigate to Apps > Web and mobile apps
    • Click Add app > Add custom SAML app
    • Configure:
      • App name: "Yellow Card Treasury Portal"
      • ACS URL: https://sso.portal.yellowcard.io/saml2/idpresponse
      • Entity ID: urn:amazon:cognito:sp:eu-west-2_XgIgQU2Xa
      • Start URL: https://portal.yellowcard.io
      • Name ID format: EMAIL
      • Name ID: Basic Information > Primary email

  2. Attribute Mapping (Required):

    NameFormatValue
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressURI ReferenceBasic Information > Primary email
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameURI ReferenceBasic Information > First name
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameURI ReferenceBasic Information > Last name
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameURI ReferenceBasic Information > Full name
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifierURI ReferenceBasic Information > Primary email

  3. In Treasury Portal:

    • Protocol: SAML
    • Metadata URL: Copy from Google Admin Console

Required Attribute Mappings

For SAML Providers

Your SAML identity provider must provide these attributes:

Attribute NameSAML ClaimDescription
emailhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressUser's email address (required for user identification)
given_namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameUser's first name
family_namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameUser's last name
namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameUser's display name
usernamehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifierSubject identifier (used as username)

For OIDC Providers

Your OIDC identity provider must provide these claims in the ID token:

Claim NameDescription
emailUser's email address (required for user identification)
given_nameUser's first name
family_nameUser's last name
subSubject identifier (used as username)

Required Scopes: openid email profile


Common Configuration Issues & Solutions

1. PKCE Configuration

⚠️

We do not currently support PKCE (Proof Key for Code Exchange).

  • For OIDC applications: Ensure PKCE is disabled or set to "Not required" in your identity provider
  • Future Support: PKCE support is planned for a future release

2. Attribute Mapping Errors

Symptoms: Users can authenticate but receive errors about missing profile information

Solutions:

  • Verify all required attributes are mapped correctly
  • Check attribute names match exactly (case-sensitive)
  • For SAML: Ensure Name ID format is set to "EmailAddress" or "Email"
  • For OIDC: Verify the email, given_name, and family_name claims are included in the ID token

3. Callback URL Mismatches

Symptoms: "Redirect URI mismatch" or "Invalid redirect URI" errors

Solutions:

  • Verify callback URLs match exactly:
    • OIDC: https://sso.portal.yellowcard.io/oauth2/idpresponse
    • SAML: https://sso.portal.yellowcard.io/saml2/idpresponse
  • Check for trailing slashes or HTTP vs HTTPS mismatches
  • Ensure URLs are added to your IdP's allowed/authorised redirect list

4. Certificate and Metadata Issues

Symptoms: SAML authentication fails with certificate or signature errors

Solutions:

  • For metadata URL: Ensure the URL is publicly accessible and returns valid XML
  • For manual configuration: Verify the X.509 certificate is valid and properly formatted
  • Check that the signing certificate matches the one used by your IdP

5. User Assignment and Access

Symptoms: Some users can't access the application even after SSO is configured

Solutions:

  • Ensure users/groups are assigned to the SSO application in your IdP
  • Check that the user email domains match your configured domain

Testing Your Configuration

⚠️

Important: Always test your SSO configuration before activating it for your organization. Testing helps identify configuration issues without affecting existing users.

Step 1: Test Connection

  1. In Treasury Portal SSO settings, click Test Connection. This does a test to confirm your issuer URL or metadata URL is valid and reachable.
  2. Verify the test passes without errors
  3. If errors occur, check the error message shown on the page to diagnose the issue.

Step 2: Test User Login

  1. Before activating, test with a single user account
  2. Open an incognito/private browser window
  3. Navigate to the Treasury Portal login page https://portal.yellowcard.io/login
  4. Enter your test user's email address
  5. Verify that the redirect to your corporate IdP occurs
  6. Complete authentication in your IdP
  7. Verify successful redirect back to the Treasury Portal
  8. Check that the user profile information is populated correctly

Security Considerations

Role Assignment

  • Important: User roles are controlled by the Treasury Portal, not your identity provider
  • Default role is view for all new SSO users
  • Role changes must be made within the Treasury Portal by an admin after user creation

Domain Security

  • Each email domain can only be associated with one SSO configuration.

JIT Provisioning Security

  • JIT provisioning is enabled by default when SSO is configured
  • Admin notifications: Organisation admins will receive an email notification when a new user is automatically provisioned and signs in for the first time

Frequently Asked Questions (FAQ)

General Questions

Q: What protocols does Yellow Card Treasury Portal support for SSO? A: We support both OIDC (OpenID Connect) and SAML 2.0. OIDC is recommended for most modern identity providers as it's easier to configure and more reliable.

Q: Can users still log in with username/password after SSO is enabled? A: Yes, unless "Enforce SSO" is enabled. When SSO enforcement is disabled, users can choose between SSO login or traditional username/password with MFA. When enforcement is enabled, only SSO login is allowed for users from your organisation's domain.

Q: How long does SSO setup typically take? A: The setup process usually takes less than 10 minutes, including configuration in both your identity provider and Treasury Portal, plus testing time.


User Management

Q: What role do new SSO users get by default? A: All new users automatically receive the view role. Admins must manually upgrade user roles after account creation if needed.

Q: Do I get notified when new users access the portal via SSO? A: Yes, organisation admins receive email notifications whenever a new user is automatically provisioned and signs in for the first time.

Q: Does Yellow Card support SCIM? A: No, Yellow Card Treasury Portal does not currently support SCIM (System for Cross-domain Identity Management). SCIM support will be included in a future release to enable automated user lifecycle management.

Q: What happens if I disable a user in my identity provider? A: The user will no longer be able to authenticate via SSO. However, their Treasury Portal account remains active until manually disabled by an admin within the portal.

Q: Can I migrate existing users to SSO without losing their data? A: Yes, existing users can continue using their accounts. When they first log in via SSO, their accounts will be linked automatically based on their email address. No data is lost during this process.



Troubleshooting

🔧

Quick Fix: Most SSO issues are caused by incorrect callback URLs or missing attribute mappings. Check these first before diving into complex troubleshooting.

Common Error Messages

ErrorCauseSolution
"Invalid redirect URI"Callback URL mismatchCheck redirect URIs in IdP configuration
"Invalid client credentials"Wrong client ID or secret for OIDCVerify credentials match IdP settings
"SAML assertion validation failed"Certificate or signature issueCheck the SAML certificate and metadata


Support Contacts

For technical assistance with SSO setup:

  1. Treasury Portal Issues: Contact your Yellow Card account manager
  2. IdP Configuration Issues: Consult your IT administrator or IdP vendor documentation
  3. Urgent Issues: Use your organisation's support channels

Updated about 4 hours ago