RETR Single Sign-On (SSO) Setup Guide

Step 1: Provide IdP Metadata to RETR

To begin the SSO setup, please send RETR your Identity Provider metadata file or metadata URL. This metadata includes the information RETR needs to establish the SAML connection (signing certificate, IdP SSO URL, entity ID, etc.).

Required SAML Attribute

Please ensure your Identity Provider is configured to send the following SAML attribute:

RETR Field	SAML Attribute	Notes
Email	email or mail	Required

Example of what an IdP Metadata URL should return

<EntityDescriptor entityID="https://idp.example.com" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
    <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <KeyDescriptor use="signing">
    <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
    <X509Data>
    <X509Certificate>MIID...ABCD</X509Certificate>
    </X509Data>
    </KeyInfo>
    </KeyDescriptor>
    <SingleSignOnService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
    Location="https://idp.example.com/sso/login" />
    </IDPSSODescriptor>
</EntityDescriptor>

Your metadata may contain additional fields, certificates, or logout URLs depending on your IdP, but must follow this general XML structure.

Step 2: RETR Configuration

After receiving your metadata, RETR will:

Configure SSO settings for your organization
Map required SAML attributes to RETR user properties
Generate and provide your team with RETR's Service Provider (SP) metadata

Example of RETR SP Metadata Provided to IdP

<EntityDescriptor entityID="https://retr.app" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
    <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <AssertionConsumerService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
    Location="https://retr.app/sso/acs"
    index="1" />
    <SingleLogoutService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
    Location="https://retr.app/account/logoff" />
    </SPSSODescriptor>
</EntityDescriptor>

Step 3: Client IdP Configuration

Once RETR completes the configuration, we will create a unique organization identifier (Organization ID/slug) and provide it to you. That slug is used in your SP metadata URL and tenant identification.

Your RETR SP Metadata URL:

https://retr.app/sso/metadata/your-organization-id

Configure RETR in Your Identity Provider

Use the provided metadata URL to configure RETR as a trusted Service Provider in your IdP. The specific steps will vary depending on your Identity Provider, but generally you will need to:

Log in to your Identity Provider's administration console
Add a new SAML application or Service Provider
Import RETR's SP metadata using the provided URL, or manually enter the following details:

Entity ID: https://retr.app

Assertion Consumer Service (ACS) URL: https://retr.app/sso/acs

Single Logout URL: https://retr.app/account/logoff
Configure the required SAML attribute mappings (email attribute as shown above)
Assign users or groups who should have access to RETR
Save and activate the configuration

Step 4: Testing and Verification

After both parties complete their configuration, RETR will coordinate with your team to:

Verify the SSO handshake is successful
Test user login flow from both SP-initiated and IdP-initiated scenarios
Confirm that user attributes (email, name, etc.) are correctly mapped and transmitted
Test Single Logout functionality (if configured)
Troubleshoot any issues that arise during testing

Note: Please notify RETR support once you have completed your IdP configuration so we can proceed with testing and verification.

Support

If you have questions or need help with metadata or SAML configuration, please contact the RETR support team at support@retr.app.

Entity ID:	`https://retr.app`
Assertion Consumer Service (ACS) URL:	`https://retr.app/sso/acs`
Single Logout URL:	`https://retr.app/account/logoff`