Social login overview

The CyberArk Identity Platform APIs 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.

Configure the Admin Portal

For more details about configuring social login in the Identity Administration portal, see Configure the integration to your social media application.

Start 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 value, 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

Handle the redirect

Your client must save the IdpRedirectUrl and pass it to a browser to send the user to the IDP 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, and 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":"ausem@mac.com",
		"UserDirectory":"FDS",
		"PodFqdn":"acme.my.idaptive.app",
		"User":"ausem@mac.com",
		"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.

Handle social IDP multi-factor authentication

If social media users are configured for multi-factor authentication, the value of the Summary field will be set to NewPackage. This indicates 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 xxxx@mac.com",
				"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.