- Introduction
- Installing and updating
- Navigating Postman
- Sending your first request
- Managing your account
- Syncing your work
- Discovering templates
- Creating your first collection
- Creating a workspace
- Setting up your Postman app
- Importing and exporting data
- Troubleshooting app issues
- Building requests
- Authorizing requests
- Receiving responses
- Grouping requests in collections
- Using variables
- Managing environments
- Visualizing responses
- Specifying examples
- Using cookies
- Working with certificates
- Generating client code
- Troubleshooting requests
- Using the Collection Runner
- Scheduling runs with monitors
- Building request workflows
- Importing data files
- Working with your team
- Defining roles
- Requesting access
- Sharing your work
- Your private API network
- Commenting on collections
- Versioning APIs
- Using version control
- Using the API Builder
- Managing and sharing APIs
- Validating APIs
- Monitoring APIs
- Setting up a monitor
- Viewing monitor results
- Monitoring APIs and websites
- Set up integrations to receive alerts
- Running Postman monitors using static IPs
- Troubleshooting monitors
- Monitoring FAQs
- Analyzing with reports
- Documenting your API
- Authoring your docs
- Publishing your docs
- Viewing documentation
- Using custom domains
- Publishing templates
- Publishing to the API Network
- Submission guidelines
- Managing your team
- Purchasing Postman
- Billing
- Configuring team settings
- Utilizing audit logs
- Onboarding checklist
- Intro to SSO
- Configuring SSO for a team
- Logging in to an SSO team
- Microsoft AD FS
- Custom SAML in Azure AD
- Custom SAML in Duo
- Custom SAML in GSuite
- Custom SAML in Okta
- Custom SAML in Onelogin
- Custom SAML in Ping Identity
- Migrating to the current version of Postman
Microsoft AD FS
Prerequisites
Before you configure Microsoft Active Directory Federation Services (AD FS) to work with Postman Single sign-on (SSO), you must have:
- An Active Directory instance where all users have an email address attribute.
- A SSL certificate from the AD FS server.
- A server that runs Microsoft Server 2012 or 2008. Note: This guide uses screenshots from Server 2012R2, but similar steps should be possible in other versions.
After you meet these basic requirements, install AD FS on your server.
To configure and install AD FS, see Deploy and configure AD FS in the Microsoft Knowledge Base.
Configuration
Follow the steps below to configure Microsoft AD FS to work with Postman SSO.
Step 1 - Create an AD FS authentication scheme in Postman.
To create this scheme authentication, see Configuring SSO for a team.
After creating the scheme, collect the values for these fields in the Team page.
| Fields | AD FS equivalent |
|---|---|
| Assertion Consumer Service URL | SAML 2.0 SSO service URL |
| Encryption Certificate | Token encryption certificate |
Step 2 - Add a Relying Party Trust.
Relying Party Trust (RPT) defines the connection between AD FS and Postman.
To add a Relying Party Trust:
Select the Relying Party Trusts folder from "AD FS Management".
On the Actions sidebar, click "Add Relying Party Trust" to start the configuration wizard for a new trust.
Click the Claims aware button in the Welcome screen and then click the Start button.
In the Select Data Source screen, select the last option, "Enter Data About the Party Manually".
Enter a "Display Name" that you'll recognize later. You can optionally add notes.
Upload the encryption certificate in the Team page or use the default certificate settings.
Check the box labeled "Enable Support" for the SAML 2.0 WebSSO protocol.
Collect the service URL (ACS URL) from the Team page.
Add this Relying party trust identifier: https://identity.getpostman.com.
Select "Permit everyone".
In the next two screens, the wizard displays an overview of your settings.
In the final screen, use the Close button to exit and open the "Claim Rules" editor.
Step 3 - Create claim rules.
After the relying party trust has been created, you can create the claim rules.
To create a new rule:
Click "Add Rule". Then create a "Send LDAP Attributes as Claims" rule.
Using the Active Directory as your attribute store, perform these actions:
In the LDAP Attribute column, select "E-Mail Addresses". In the Outgoing Claim Type, select "E-Mail Address".
Click the Finish button to save the new rule.
Click "Add Rule" to create another new rule and select "Transform an Incoming Claim" as the template.
In the next screen perform these actions:
In "Incoming Claim Type", select "E-mail Address".
In "Outgoing Claim Type", select "Name ID".
In "Outgoing Name ID Format", select "Email".
Note: Use the default setting: "Pass through all claim values".
Click the Finish button to create the claim rule.
You should see two transform rules. Click "Edit Claim Issuance Policy" to confirm.
Step 4 - Adjust the trust settings.
To adjust the trust settings, select "RPT" and then select "Properties" in the Actions sidebar.
In the Advanced tab, specify "SHA-1" as the secure hash algorithm.
Step 5 - Submit Identity Provider details to Postman.
After the setup, you must submit your Identity Provider's details to Postman.
Download the FederationMetadata.xml. You can generally find this file at: https://<Federation Service name>/FederationMetadata/2007-06/FederationMetadata.xml
Collect the Identity Provider Single Sign-On URL, Identity Provider Issuer, and X.509 Certificate from the metadata file and enter these values in the Team page in the AD FS Identity Provider Details dialog.
Step 6 Enable the RelayState parameter on your ADFS servers.
- For ADFS 2.0, open the following file in a text editor:
%systemroot%\inetpub\adfs\ls\web.config
- For ADFS 3.0, open the following file in a text editor:
%systemroot%\ADFS\Microsoft.IdentityServer.Servicehost.exe.config
In the <microsoft.identityServer.web> section, add a line for useRelyStateForIdpInitiatedSignOn as follows, and save the change:
<microsoft.identityServer.web> ... <useRelayStateForIdpInitiatedSignOn enabled="true" /> ...</microsoft.identityServer.web>
- For ADFS 2.0, run IISReset to restart IIS.
- For both platforms, restart the Active Directory Federation Services (adfssrv) service.
If you're using ADFS 3.0 you only need to do the above on your ADFS 3.0 servers, not the WAP servers.
Ensure that <useRelayStateForIdpInitiatedSignOn enabled="true" /> has been added at microsoft.identityServer.web, then generate a URL encoded string from the relay state and the Entity ID as follows.
- There are two pieces of information you need to generate the RelayState URL. The first is the relying party's identifier, which can be found in the AD FS Management Console. View the Identifiers tab on the relying party's property page.
- The second part is the actual RelayState value that you need to send to the relying Party. The example below uses the relying party identifier of
https://identity-example.getpostman.comand the relay state of35ef7ab89gh99hh00.
Starting values:
- RPID:
https://identity-example.getpostman.com - Relay State:
35ef7ab89gh99hh00
You are advised to use a trusted URL encoder to generate the encode values.
URL encode each value.
- RPID:
https%3A%2F%2Fidentity-example.getpostman.com - Relay State:
35ef7ab89gh99hh00
Merge the URL encoded values with the string below, and URL encode the whole string.
- String:
RPID=<URL encoded RPID>&RelayState=<URL encoded RelayState> - String with values:
RPID=https%3A%2F%2Fidentity-example.getpostman.com&RelayState=35ef7ab89gh99hh00 - URL encoded string:
RPID%3Dhttps%253A%252F%252Fidentity-example.getpostman.com%26RelayState%3D+35ef7ab89gh99hh00
Take the final string and append it to the IDP initiated sign-on URL.
- An example IDP initiated sign-on URL would have the following structure:
https://adfs.contoso.com/adfs/ls/idpinitiatedsignon.aspx - Final URL:
https://adfs.contoso.com/adfs/ls/idpinitiatedsignon.aspx?RelayState=RPID%3Dhttps%253A%252F%252Fidentity-example.getpostman.com%26RelayState%3D+35ef7ab89gh99hh00
Navigate to the final URL in the browser on first time login from Azure AD, which will enable setting the relay state and allow seamless SSO login in future.