GuidesAPI ReferenceGitHub
Guides
Community ForumsTwitter

Social Login

Social Login

The Centrify Identity Platform API's enable your client to log a user in by using a third party social IDP. Centrify 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.

Cloud Manager Configuration

To enable your client to authenticate users through social media, you must set up a trust relationship with the IDP in the Cloud Manager, as follows:

  1. Log in to Cloud Manager and click Settings, Users, Social Login.
  2. Select one or more of the social-identity providers (such as Facebook).
  3. Click Save to save your selections.

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 a single body parameter, IdpName, with a keyword to identify the name of the IDP to contact. The following example shows a request to authenticate a user through Facebook:

POST https://ABC1234.mycompany.centrify.com/Security/StartSocialAuthentication


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


{
     "IdpName": "Facebook",
}

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.centrify.com%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 Centrify-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.centrify.com/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.centrify.com: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.centrify.com: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.centrify.com",
          "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 about 5 years ago