HomeProduct documentationGitHubCyberArk developer community

Social Login

Suggest Edits

Social Login

The CyberArk Identity Platform API's enable your client to log a user in by using a third party social IDP. CyberArk Identity currently supports the following IDPs: Facebook, Google, LinkedIn, and Microsoft.

The API requires that your client configure redirection and callback URLs to use in authenticating through an IDP. It must redirect the user to the IDPs login screen, where the users can enter their credentials. Once the IDP authenticates the user, it redirects the user back to the client using a callback URL. The callback function that the client provides to the IDP also includes your client's tenant ID and an ID for the MFA session.

Admin Portal Configuration

Refer to Idaptive product documentation for details about configuring social login in the Admin Portal, particularly the section "Configuring the integration to your social media application".

Starting the Social Authentication Process

The first step in authenticating a user through a social media IDP is to invoke /Security/StartSocialAuthentication. This endpoint takes the following parameters:

  • IdpName, with a keyword to identify the name of the IDP to contact
  • PostExtIdpAuthCallbackUrl, with a URL that the social login API can use to redirect back to the calling site

The following example shows a request to authenticate a user through Facebook:

POST https://ABC1234.mycompany.idaptive.app/Security/StartSocialAuthentication


X-IDAP-NATIVE-CLIENT:true
Content-Type: application/json


{
     "IdpName": "Facebook",
     "PostExtIdpAuthCallbackUrl": "https://myapp.mycompany.com",
}

The response from the server includes the IdpRedirectUrl field containing the URL of the social login screen to which your client must redirect the user, and a Status, which is set to RedirecToIdp, indicating that the user is to be redirected to an IDP:

{
IdpRedirectUrl=https://www.facebook.com/dialog/oauth?client_id=1513153205663776&redirect_uri=https%3a%2f%2fpod1.idaptive.app%2fSocialAuth%2fFacebookAuthCallback&state=ABC0123-64f226d5-a237-42dd-b344-897234189534&response_type=code&scope=public_profile,email
Status=RedirectToIdp
}

The IdpRedirectUrl value includes the following elements:

  • URL: The CyberArk Identity -specific user-access page for the IDP.
  • Redirect_uri: The REST API callback function that the IDP is to call after authenticating the user.
  • State: The tenant ID (for example, ABC0123) and the MFA session ID (for example 64f226d5).
  • Response_type: The expected response, set to code.
  • Scope: The elements to return from the IDP, set to public_profile,email.

Handling the Redirect

Your client must save the IdpRedirectUrl and pass it to a browser to send the user to the IDP’s login screen. Once the user provides credentials on that screen, the IDP returns the user to the original MFA session by executing the callback function that was provided in the response:

https://pod1.idaptive.app/SocialAuth/FacebookAuthCallback
{
        "code": AQBGtF1mNRKICYoJyUZueV8mo7kvsVe6F4Klph2eJUQ1naL-GDqHMxf_NIY7JmLLhnVOIfTFGu-sJC6oERVX7R1kjofFiP_z_KM8e5-pbZGMwW9BSNML6gSgjR1AEiiKwHLfeqQwqdZA2WZYYr7QS52q0q8P76B6Y8TN5ivEhvBBNgClhlxXC7bqkiYYkB_Uchc0wAB3x_jeSw5jHkGbNimWRz4-wo1ylk5bV8YSioiFHE8QwfuoNc7H-hFqWF1mmvuVIJOhYA03zeX6lCk61FApqEuPcMKIRrRnLE8S8ULr0k9Pu7QS5Gnr66l-9nyCsJbeJkSimQkcR1zxEs9AnHGz
         "state": ABC0123-64f226d5-a237-42dd-b344-897234189534
}

For a successful login, the function returns a URL similar to the following:

https://acme.my.idaptive.app:443/my?customerId=ABC0123&ExtIdpAuthChallengeState=ABC0123-64f226d5-a237-42dd-b344-897234189534&username=ausem%40mac.com

The URL identifies the Identity Service login session that invoked the IDP to authenticate the user, and provides the email name of the user. Your client must pass this URL to a browser, then call /Security/ResumeFromExtIdpAuth to log in the user:

https://acme.my.idaptive.app:443/my?customerId=ABC0123&ExtIdpAuthChallengeState=ABC012364f226d5-a237-42dd-b344-897234189534&username=auser%40mac.com
/Security/ResumeFromExtIdpAuth

/Security/ResumeFromExtIdpAuth returns results similar to the following example:

{
        "success":true,
        "Result":
         {
          "AuthLevel":"Normal",
          "DisplayName":"Allen Usem","Auth":"B6A7A89962BC...",
          "UserId":"db6244dd-8632-5748-664e-225c700432a7",
          "EmailAddress":"[email protected]",
          "UserDirectory":"FDS",
          "PodFqdn":"acme.my.idaptive.app",
          "User":"[email protected]",
          "CustomerID":"ABC0123",
          "SystemID":"ABC0123",
          "SourceDsType":"FDS",
          "Summary":"LoginSuccess"
         },
        "Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null
}

The Summary field contains a LoginSuccess value, indicating that the IDP authenticated the user.

Handling Social IDP Multifactor Authentication

If social media users are configured for multi-factor authentication, the Summary field’s value will be set to NewPackage indicating that the call to /Security/ResumeFromExtIdpAuth has returned a new MFA package that contains a Challenge array where each element contains Mechanisms for the user to respond to. The following example response shows a new MFA package with a single email challenge returned by /Security/ResumeFromExtIdpAuth:

{
        "success":true,
        "Result":
        {
         "ClientHints":
          {"PersistDefault":false,"AllowPersist":false,"AllowForgotPassword":false},
         "Version":"1.0",
         "SessionId":"jf3eH91wqUqy2sxQQAokuoGCS9uJ63EIoLNLVAbZ60E1",
         "Challenges":
          [{"Mechanisms":
           [{
                "AnswerType":"StartOob",
                "Name":"EMAIL",
                "PromptMechChosen":"Click the link in the email sent to [email protected]",
                "PromptSelectMech":"Email... @mac.com","PartialAddress":"mac.com", 
                "MechanismId":"ZbaHqYKZFUyI45AP0sYUgMXK5IaIzJH8YiIAy9ekklk1"
           }]
          }],
         "Summary":"NewPackage",
         "TenantId":"ABC0123"
        }, 
         
        "Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null
}

Your client must then advance the authentication by invoking /Security/AdvanceAuthentication with the TenantId, SessionId, and MechanismId specified in the response, as described in Advancing the Authentication earlier in this tutorial.

Updated 6 months ago