Qodex.ai

Sign-on using an External Identity Provider

Number of APIs: 27

This activity shows you how to test the external authentication flow to sign-on using an external identity provider (IdP).

The easiest way to do this is by using two PingOne environments. One environment will act as the service provider (SP) for an OIDC application, while the other environment is used to configure an OIDC identity provider (IdP) connection.

This activity requires completing an internal authentication flow within the external authentication flow, so it's important to take note of which environment should be used to complete each step. On the first use of external authentication, you will need to link accounts. This takes place in step 25 of this activity. After the accounts are linked once, you will not need to link them again and can omit step 25 in the future.

Prerequisites

  • Get an access token from the worker application that you created in Getting Started with the PingOne APIs.

  • A destination PingOne environment to act as the service provider (SP) for the OIDC application. You'll use this environment to configure the OIDC IdP connection. Authentication flows in this environment can be configured to allow external authentication.

  • A source PingOne environment that will act as the OIDC IdP. Users here will be able to complete authentication flows in the destination environment.

  • Cross-environment admin permissions for the destination and source environments.

This scenario illustrates the following operations supported by the PingOne APIs:

  • Create an OIDC application in the source environment.
  • Create an OIDC IdP in the destination environment referencing the source application.
  • Create a sign-on policy in the destination environment.
  • Create a sign-on policy action to enable the sign-on policy for the OIDC IdP connection.
  • Set the sign-on policy as the default for the destination environment.
  • Create an OIDC application in the destination environment.
  • Set the sign-on policy as the default for the destination environment.
  • Create a population in the source and destination environments.
  • Create users in the source and destination environments.
  • Initiate an authorization request.
  • Read an external authentication initialization.
  • Send an external authentication request.
  • Get the flow for an external identity provider.
  • Pass in external identity provider credentials for verification.
  • Retrieve an authorization code from the authorization server by calling the resume endpoint.
  • Call the external authentication callback to get the response from an external identity provider.
  • Get the flow and submit credentials for account linking.
  • Retrieve an authorization code from the authorization server by calling the resume endpoint.
  • Exchange an authorization code for an access token.

Workflow order of operations

To test the external authentication flow to sign-on using an external identity provider, the following tasks must be completed successfully:

  1. Make POST requests to /environments to create a source environment and a destination environment.

  2. Make a POST request to /environments/{{sourceEnvID}}/applications to create an OIDC application in the source environment.

  3. Make a GET request to /environments/{{sourceEnvID}}/applications/{{appID}}/secret to read the OIDC application secret.

  4. Make a POST request to /environments/{{destinationEnvID}}/identityProviders to create an OIDC IdP in the destination environment.

  5. Make a POST request to /environments/{{destinationEnvID}}/signOnPolicies to create a sign-on policy for the IdP in the destination environment.

  6. Make a POST request to /environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}/actions to create a new IDENTIFIER_FIRST sign-on policy action associated with the new sign-on policy.

  7. Make a PUT request to /environments/{{destinationEnvID}}/signOnPolicies/{{policyID}} to set the policy as default.

  8. Make a POST request to /environments/{{destinationEnvID}}/applications to create an OIDC application in the destination environment.

  9. Make a GET request to /environments/{{destinationEnvID}}/applications/{{oidcAppDestinationID}}/secret to read the application secret in the destination.

  10. Make a POST request to /environments/{{destinationEnvID}}/applications/{{appID}}/signOnPolicyAssignments to assign the sign-on policy to the destination OIDC application.

  11. Make a POST request to /environments/{{sourceEnvID}}/populations to create a population in the source environment.

  12. Make a POST request to /environments/{{destinationEnvID}}/populations to create a population in the destination environment.

  13. Make a POST request to /environments/{{sourceEnvID}}/users to create a user in the source environment.

  14. Make a POST request to /environments/{{destinationEnvID}}/users to create a user in the destination environment.

  15. Make a PUT request to /environments/{{sourceEnvID}}/users/{{SourceUserID}}/password to set the source user's password.

  16. Make a PUT request to /environments/{{destinationEnvID}}/users/{{DestinationUserID}}/password to set the destination user's password.

  17. Make a GET request to /{{destinationEnvID}}/as/authorize to retrieve an authorization grant.

  18. Make a GET request to /{{destinationEnvID}}/rp/authenticate?providerId={{oidcProviderID}}&flowId={{flowID}} to read the external authentication initialization.

  19. Make a GET request to /{{sourceEnvID}}/as/authorize?response_type=code&redirect_uri=https://auth.pingone.com/{{destinationEnvID}}/rp/callback/openid_connect&scope=openid&client_id={{oidcAppSourceID}}&nonce={{nonce}}&state={{externalProviderState}} to send the external authorization request to the IdP.

  20. Make a GET request to /{{sourceEnvID}}/flows/{{flowID}} to get the flow for the external IdP.

  21. Make a POST request to /{{sourceEnvID}}/flows/{{flowID}} to submit the credentials for the external IdP.

  22. Make a GET request to /{{sourceEnvID}}/as/resume?flowId={{flowID}} to call the resume endpoint for the external IdP.

  23. Make a GET request to /{{destinationEnvID}}/rp/callback/{{providerType}}?code={{authCode}}&state={{externalProviderState}}&nonce={{nonce}} to call the external authentication callback endpoint and get the response from the external identity provider.

  24. Make a GET request to /{{destinationEnvID}}/flows/{{flowID}} to retrieve the flow needed for account linking.

  25. Make a POST request to /{{destinationEnvID}}/flows/{{flowID}} to submit the credentials for account linking.

  26. Make a GET request to /{{destinationEnvID}}/as/resume?flowId={{flowID}} to call the resume endpoint.

  27. Make a POST request to /{{destinationEnvID}}/as/token to retrieve the access token.

  1. Step 7: Set the sign-on policy as the default PUT {{apiPath}}/environments/{{destinationEnvID}}/signOnPolicies/{{oidcSignonPolicyID}}

  2. Step 1b: Create Destination Environment POST {{apiPath}}/environments

  3. Step 2: Create an OIDC application in the source environment POST {{apiPath}}/environments/{{sourceEnvID}}/applications

  4. Step 3: Read the OIDC application secret GET {{apiPath}}/environments/{{sourceEnvID}}/applications/{{oidcAppSourceID}}/secret

  5. Step 14: Create a destination user POST {{apiPath}}/environments/{{destinationEnvID}}/users

  6. Step 15: Set source user password PUT {{apiPath}}/environments/{{sourceEnvID}}/users/{{SourceUserID}}/password

  7. Step 16: Set destination user password PUT {{apiPath}}/environments/{{destinationEnvID}}/users/{{DestinationUserID}}/password

  8. Step 23: Call the external authentication callback endpoint GET {{authPath}}/{{destinationEnvID}}/rp/callback/{{providerType}}?code={{authCode}}&state={{externalProviderState}}&nonce={{nonce}}

  9. Step 4: Create OIDC identity provider in destination environment POST {{apiPath}}/environments/{{destinationEnvID}}/identityProviders

  10. Step 5: Create a sign-on policy for the OIDC IdP POST {{apiPath}}/environments/{{destinationEnvID}}/signOnPolicies