API Documentation
Post on 21-Dec-2015
95 Views
Preview:
DESCRIPTION
Transcript
1 Integration Guide 211 Granting temporary access to public server for SCP 212 OAuth 20 Clients 213 OAuth 20 Integration 314 OAuth 20 Integration Endpoints Sample Requests and Sample Responses 1215 PingFederate SAML Vs OpenToken 1416 PingFederate and CloudHSM Integration 1417 PingFederate OAuth Vs OpenAM OAuth 1518 PingFederate TimeOut Values 1619 SocialIDM User Instructions 16110 User Profile Integration 21
2 API 2521 User Profile Management APIs 27
211 Add User Profile 27212 Get User Profile 27213 Update User Profile 29214 Search Users 30215 Deactivate an account 33216 LinkUnlink Account 34
22 Credential Management APIs 34221 Credential Management Admin Password Reset 34222 Credential Management Change Password 35223 Credential Management Get Credential 36224 Credential Management KBA 38225 Credential Management OTP 41
23 JSON Schema 43231 Sample JSON Payloads 44
1 a b
1 a
2 3
a b c
4 a
1
a
1
2 a
b 3 4
Integration GuideRefer to the following chapters for integration
Granting temporary access to public server for SCPOAuth 20 ClientsOAuth 20 IntegrationOAuth 20 Integration Endpoints Sample Requests and Sample ResponsesPingFederate SAML Vs OpenTokenPingFederate and CloudHSM IntegrationPingFederate OAuth Vs OpenAM OAuthPingFederate TimeOut ValuesSocialIDM User InstructionsUser Profile Integration
Granting temporary access to public server for SCP
Setting up Access
To provide scp access without shell access
Install rssh package on hostyum install rsshchmod og+rx usrbinrssh
For each user to be added (username ncr1 as an example)
Create unix account on EC2-hostuseradd -m -d homencr1 -s usrbinrssh ncr1
Ask Account owner to generate ssh keypair using ssh-keygen and send ssh public key to usDrop received ssh public key to users sshauthorized_keys
mkdir homencr1sshchown ncr1 homencr1sshchmod 600 homencr1ssh
The default for rssh is deny all scp and sftp access Enable ncr1 to use scp under rssh by adding the following line to etcrsshconfuser= ncr101100001
Disable Access
To Disable ncr1 user to use scp remove the above line or change it to
user= ncr101100000
Process to grant accessAccess is via scp using ssh keypairs ( scp allows moving files only and has no GUI support sftp is required for listing contents anddirectory operations)2 Client requiring access need to generate ssh keypair and send us the public key The key should be SSH2 1024-bit RSA
On windows running putty use puttygen Refer to Putty documentationhttpwinscpnetengdocsui_puttygenobtaining_and_starting_puttygenOn OSX or linux the command to generate ssh key is usually ssh-keygen
Transfer the ssh public key to CRN OpsCRN Ops use the steps above to grant user scpsftp access and provide the connection info once setup is completed
Connection Information
Name IP Address
Public IP for OpenVPN 54842212
Intranet IP 1000171
OAuth 20 Clients
1 2 3
Clients ConfiguredFollowing are the clients configured in PingFederate
Client Id Component Grant Types Supported
Pl0QC2Y1fAxX57V5K2uFcarVjDbflN SocialIDM Resource owner password credentials Grant type
pingfederate PingFederate Resource owner password credentials Grant type
axway_rs AxWay urnpingidentitycomoauth2grant_typevalidate_bearer
lS9qHlAEZwY4pSC4fIucAkzdemcaF8 NCR Mobile Ordering Mobile App authorization_code
6BE789472A038F0292AE1BD022434A NCR Mobile Ordering Resource Server urnpingidentitycomoauth2grant_typevalidate_bearer
MobileAppV1 Chick-fil-A Flag Ship Mobile App authorization_code
W6K5MVJSpEIsiIxmdO7KrtZKZXtgch Chick-fil-A Testing Team Resource owner password credentials Grant type
OAuth 20 Integration
Introduction
Chick-fil-A Inc is engaged in a multi-year multi-phased project to build a Customer Identity Management System to centralize the functionality ofauthentication authorization and user management The integrating service providers can leverage this system for the following
AuthenticationAuthorization to access an HTTP ServiceRESTful API to access users identity profile based on authorization granted as part of the step 2
The document describes integration capabilities of Customer Identity Management System and to define the integration interfaces
Glossary
Term Definition
Resource server(API server)
The server that hosts the protected resources capable of accepting and responding to the protected resource requestsby using the access tokens
ClientApplication An application that makes the protected resource requests on behalf of the end user The term client does not implyany particular implementation characteristics for the application executes on a server a desktop orexample whetherother devices
Authorizationserver
The server that issues access tokens to the client after successfully authenticating the resource owner and obtainingauthorization
AuthorizationCodeAuthorizationToken
The authorization code is obtained by using an authorization server as an intermediary between the client and the enduser It is used to authenticate the client and grant the transmission of the access token This is the token thatauthorization server issues to the clients that can be swapped for an access token It has a very short lifetime since theswap must be performed immediately after users provide their authorization
Access Token A token required to access the resources protected by OAuth 20 The access token has an expiry time and is active for12 minutes
Refresh Token A token that the authorization server issues to clients and can be swapped for a brand new access token withoutrepeating the authorization process The refresh token has an expiry time and is active for 30 days
References
Reference Documentation
OAuth 20 Specification
Refer to this location for the final version of the specificationhttptoolsietforghtmlrfc6749
OAuth 20 Clients
Refer to this location to view OAuth 20 Clientshttpoauthnet2
OAuth 20 Development Tools
Tool Location
Chrome REST Client httpschromegooglecomwebstoredetailadvanced-rest-clienthgmloofddffdnphfgcellkdfbfbjeloohl=en-US
Firefox REST Client httpsaddonsmozillaorgen-USfirefoxaddonrestclient
Standards in Solution
OAuth 20
OAuth 20 is the Authorization standard used in this proposed solution As per RFC OAuth 20 authorization framework enables a third-partyapplication to obtain limited access to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction between theresource owner and the HTTP service or by allowing the third-party application to obtain access on its own behalf In simple terms OAuthprovides an API based security solution that does not require customers to pass on their user name and password to the resource server
IntegrationRefer to Figure 1 that depicts the integration process
Figure 1 Integration process
Registration
All applications that can access a Chick-fil-A APIs must be registered The registration is currently an offline process The result of this registrationprocess is a client ID and client secret shared between Chick-fil-A and integrating application The set of variable values is based on the type ofapplication that you are building For example a JavaScript application does not require a secret but a web server application requires
Integration With OAuth Authorization Server
To begin by using OAuth 20 the integrating client requires the following details
The URL of the service being accessedThe Auth scope which is a string that defines the specific type of access app is asking forA client ID and client secret which are strings that identify the app to the service OAuth 20 requires client registration that limits the APIaccess to register the clients only Within Customer Identity Management System client_id and client_secret are required for clientauthentication The service integration team must obtain these strings directly from the Customer Identity Management team
Environment
Specific End-Point URLs
1 2 3 4
Environment End-point URLs
Dev httpslogindevcrndevchick-fil-acom
Stage httpsloginqacrndevchick-fil-acom
Prod httpsloginchick-fil-acom
Note Use a dynamic configuration file to access these URLs The service URLs may change as part of the service upgrade
OAuth 20 End-Points
Use End-point Description
Authorizationcode
asauthorizationoauth2 Used by the OAuth AS to interact directly with the resource owners authenticate them and obtainauthorization
Accesstoken
astokenoauth2 Used by the client to obtain an access token and possibly a refresh token by presenting itsauthorization grantrefresh token This endpoint accepts only the HTTP POST method
TokenValidation
astokenoauth2 Used by the client to validate an access token
Token Info oauth2tokeninfo Getting token information
OAuth Grants
There are four different types of OAuth 20 grants they are
Authorization code grantImplicit grantResource owner password credentials grantClient cre grantdentials
The OAuth ch is used in this solution is an Authorization code grant The scenarios explained below are based on Authorization codeGrant whigrant
OAuth 20 Authorization Grant
The authorization code grant starts with the client redirecting the resource owners user-agent to ede orization service After the PingF rate authauthe icating the re ource owner and obtaining the resource owners authorization PingFederate redirects the resource owners user-agent backnt sto the cl nt wit an authorization code that the client uses to request the access token ie hFigure 2 outlines a successful process from the initial client redirection to the client accessing t protected resourche e
Figu e 2 Aut rization code grant sequencer ho
Scopes Within the Solution
The authorization scope is a string that defines the specific type of access the application is asking for The scope in this solution is usually aservice URI The Chick-fil-A authorization server does not explicitly prompt the end user for authorization The authorization server currentlygrants access to the following scopes where each scope has corresponding list of user profile attributes accessible as part of the token i ormationfn service call
Scope User Attributes Accessible
TODO
TODO
Integration With OAuth Resource Server
REST Web Services Security
All the incoming requests are authenticated based on OAuth 20Unless specified all the REST web services must send a valid OAuth 20 access token in the header
Including OAuth Access Token (REST Web Services)
For all the REST Web Service the OAuth Access token must be included in the HTTP header The name and format of the HTTP header is asfollows
Name Value
Header Name Authorization
Header Value Bearer ltltOAuth Access Tokengtgt
Example Authorization Bearer efa8c03f-9557-422a-8d75-284e3e86a1c4
Using Refresh Token
A refresh token is a string that represents the authorization granted to the client by the resource owner The string is usually not visible to theclient The token denotes an identifier used to retrieve the authorization information Unlike access tokens refresh tokens are intended for useonly with the authorization servers and are never sent to the resource servers
Figure 3 Refreshing an expired access token
Sample Use Cases and ScreenshotsThe given sample use cases and screenshots are about how to obtain an OAuth access token based on authorization_code grant type Forcomplete end point details please refer to OAuth 20 Integration Endpoints Sample Requests and Sample Responses
End-Point URL to Authorize
HTTP (GET)httpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=MobileAppV1ampscope=sessionidmeampredirect_uri=httplocalhost9090redirectltltREDIRECT_URLgtgt is the final URL which the webpage is redirected upon successful aut ntication and authorization The mobile app musthedetect the URL retrieve the authoriza on code from the query string and close the webviewti
Figure 4 depicts the sequence to obtain the access and refresh tokens
Figure 4 ining the access and refresh tokens Sequence for obta
Refer to the following screenshots on how authorization codeto obtain an
HTTP Get to the above URL in a web page and the logon page opens
Figure 5 Logon page
Enter the username and password
Figure 6 Entering user credentials
The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning httpsltltREDIRECT_URLgtgtcode=ltltoauth_autho ation_coderiz gtgt
The code oauth_authorization_code is reused at the next step to trade it for the access en and refresh tokentok
En Point URL to Access an Access Tokend-
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoau 2code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwABampgrant_type=authorization_cothdeampclient_id=MobileAppV1ampredirect_uri=ltgt
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code
Access token and refresh tokens are returned as JSON
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
1 a b
1 a
2 3
a b c
4 a
1
a
1
2 a
b 3 4
Integration GuideRefer to the following chapters for integration
Granting temporary access to public server for SCPOAuth 20 ClientsOAuth 20 IntegrationOAuth 20 Integration Endpoints Sample Requests and Sample ResponsesPingFederate SAML Vs OpenTokenPingFederate and CloudHSM IntegrationPingFederate OAuth Vs OpenAM OAuthPingFederate TimeOut ValuesSocialIDM User InstructionsUser Profile Integration
Granting temporary access to public server for SCP
Setting up Access
To provide scp access without shell access
Install rssh package on hostyum install rsshchmod og+rx usrbinrssh
For each user to be added (username ncr1 as an example)
Create unix account on EC2-hostuseradd -m -d homencr1 -s usrbinrssh ncr1
Ask Account owner to generate ssh keypair using ssh-keygen and send ssh public key to usDrop received ssh public key to users sshauthorized_keys
mkdir homencr1sshchown ncr1 homencr1sshchmod 600 homencr1ssh
The default for rssh is deny all scp and sftp access Enable ncr1 to use scp under rssh by adding the following line to etcrsshconfuser= ncr101100001
Disable Access
To Disable ncr1 user to use scp remove the above line or change it to
user= ncr101100000
Process to grant accessAccess is via scp using ssh keypairs ( scp allows moving files only and has no GUI support sftp is required for listing contents anddirectory operations)2 Client requiring access need to generate ssh keypair and send us the public key The key should be SSH2 1024-bit RSA
On windows running putty use puttygen Refer to Putty documentationhttpwinscpnetengdocsui_puttygenobtaining_and_starting_puttygenOn OSX or linux the command to generate ssh key is usually ssh-keygen
Transfer the ssh public key to CRN OpsCRN Ops use the steps above to grant user scpsftp access and provide the connection info once setup is completed
Connection Information
Name IP Address
Public IP for OpenVPN 54842212
Intranet IP 1000171
OAuth 20 Clients
1 2 3
Clients ConfiguredFollowing are the clients configured in PingFederate
Client Id Component Grant Types Supported
Pl0QC2Y1fAxX57V5K2uFcarVjDbflN SocialIDM Resource owner password credentials Grant type
pingfederate PingFederate Resource owner password credentials Grant type
axway_rs AxWay urnpingidentitycomoauth2grant_typevalidate_bearer
lS9qHlAEZwY4pSC4fIucAkzdemcaF8 NCR Mobile Ordering Mobile App authorization_code
6BE789472A038F0292AE1BD022434A NCR Mobile Ordering Resource Server urnpingidentitycomoauth2grant_typevalidate_bearer
MobileAppV1 Chick-fil-A Flag Ship Mobile App authorization_code
W6K5MVJSpEIsiIxmdO7KrtZKZXtgch Chick-fil-A Testing Team Resource owner password credentials Grant type
OAuth 20 Integration
Introduction
Chick-fil-A Inc is engaged in a multi-year multi-phased project to build a Customer Identity Management System to centralize the functionality ofauthentication authorization and user management The integrating service providers can leverage this system for the following
AuthenticationAuthorization to access an HTTP ServiceRESTful API to access users identity profile based on authorization granted as part of the step 2
The document describes integration capabilities of Customer Identity Management System and to define the integration interfaces
Glossary
Term Definition
Resource server(API server)
The server that hosts the protected resources capable of accepting and responding to the protected resource requestsby using the access tokens
ClientApplication An application that makes the protected resource requests on behalf of the end user The term client does not implyany particular implementation characteristics for the application executes on a server a desktop orexample whetherother devices
Authorizationserver
The server that issues access tokens to the client after successfully authenticating the resource owner and obtainingauthorization
AuthorizationCodeAuthorizationToken
The authorization code is obtained by using an authorization server as an intermediary between the client and the enduser It is used to authenticate the client and grant the transmission of the access token This is the token thatauthorization server issues to the clients that can be swapped for an access token It has a very short lifetime since theswap must be performed immediately after users provide their authorization
Access Token A token required to access the resources protected by OAuth 20 The access token has an expiry time and is active for12 minutes
Refresh Token A token that the authorization server issues to clients and can be swapped for a brand new access token withoutrepeating the authorization process The refresh token has an expiry time and is active for 30 days
References
Reference Documentation
OAuth 20 Specification
Refer to this location for the final version of the specificationhttptoolsietforghtmlrfc6749
OAuth 20 Clients
Refer to this location to view OAuth 20 Clientshttpoauthnet2
OAuth 20 Development Tools
Tool Location
Chrome REST Client httpschromegooglecomwebstoredetailadvanced-rest-clienthgmloofddffdnphfgcellkdfbfbjeloohl=en-US
Firefox REST Client httpsaddonsmozillaorgen-USfirefoxaddonrestclient
Standards in Solution
OAuth 20
OAuth 20 is the Authorization standard used in this proposed solution As per RFC OAuth 20 authorization framework enables a third-partyapplication to obtain limited access to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction between theresource owner and the HTTP service or by allowing the third-party application to obtain access on its own behalf In simple terms OAuthprovides an API based security solution that does not require customers to pass on their user name and password to the resource server
IntegrationRefer to Figure 1 that depicts the integration process
Figure 1 Integration process
Registration
All applications that can access a Chick-fil-A APIs must be registered The registration is currently an offline process The result of this registrationprocess is a client ID and client secret shared between Chick-fil-A and integrating application The set of variable values is based on the type ofapplication that you are building For example a JavaScript application does not require a secret but a web server application requires
Integration With OAuth Authorization Server
To begin by using OAuth 20 the integrating client requires the following details
The URL of the service being accessedThe Auth scope which is a string that defines the specific type of access app is asking forA client ID and client secret which are strings that identify the app to the service OAuth 20 requires client registration that limits the APIaccess to register the clients only Within Customer Identity Management System client_id and client_secret are required for clientauthentication The service integration team must obtain these strings directly from the Customer Identity Management team
Environment
Specific End-Point URLs
1 2 3 4
Environment End-point URLs
Dev httpslogindevcrndevchick-fil-acom
Stage httpsloginqacrndevchick-fil-acom
Prod httpsloginchick-fil-acom
Note Use a dynamic configuration file to access these URLs The service URLs may change as part of the service upgrade
OAuth 20 End-Points
Use End-point Description
Authorizationcode
asauthorizationoauth2 Used by the OAuth AS to interact directly with the resource owners authenticate them and obtainauthorization
Accesstoken
astokenoauth2 Used by the client to obtain an access token and possibly a refresh token by presenting itsauthorization grantrefresh token This endpoint accepts only the HTTP POST method
TokenValidation
astokenoauth2 Used by the client to validate an access token
Token Info oauth2tokeninfo Getting token information
OAuth Grants
There are four different types of OAuth 20 grants they are
Authorization code grantImplicit grantResource owner password credentials grantClient cre grantdentials
The OAuth ch is used in this solution is an Authorization code grant The scenarios explained below are based on Authorization codeGrant whigrant
OAuth 20 Authorization Grant
The authorization code grant starts with the client redirecting the resource owners user-agent to ede orization service After the PingF rate authauthe icating the re ource owner and obtaining the resource owners authorization PingFederate redirects the resource owners user-agent backnt sto the cl nt wit an authorization code that the client uses to request the access token ie hFigure 2 outlines a successful process from the initial client redirection to the client accessing t protected resourche e
Figu e 2 Aut rization code grant sequencer ho
Scopes Within the Solution
The authorization scope is a string that defines the specific type of access the application is asking for The scope in this solution is usually aservice URI The Chick-fil-A authorization server does not explicitly prompt the end user for authorization The authorization server currentlygrants access to the following scopes where each scope has corresponding list of user profile attributes accessible as part of the token i ormationfn service call
Scope User Attributes Accessible
TODO
TODO
Integration With OAuth Resource Server
REST Web Services Security
All the incoming requests are authenticated based on OAuth 20Unless specified all the REST web services must send a valid OAuth 20 access token in the header
Including OAuth Access Token (REST Web Services)
For all the REST Web Service the OAuth Access token must be included in the HTTP header The name and format of the HTTP header is asfollows
Name Value
Header Name Authorization
Header Value Bearer ltltOAuth Access Tokengtgt
Example Authorization Bearer efa8c03f-9557-422a-8d75-284e3e86a1c4
Using Refresh Token
A refresh token is a string that represents the authorization granted to the client by the resource owner The string is usually not visible to theclient The token denotes an identifier used to retrieve the authorization information Unlike access tokens refresh tokens are intended for useonly with the authorization servers and are never sent to the resource servers
Figure 3 Refreshing an expired access token
Sample Use Cases and ScreenshotsThe given sample use cases and screenshots are about how to obtain an OAuth access token based on authorization_code grant type Forcomplete end point details please refer to OAuth 20 Integration Endpoints Sample Requests and Sample Responses
End-Point URL to Authorize
HTTP (GET)httpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=MobileAppV1ampscope=sessionidmeampredirect_uri=httplocalhost9090redirectltltREDIRECT_URLgtgt is the final URL which the webpage is redirected upon successful aut ntication and authorization The mobile app musthedetect the URL retrieve the authoriza on code from the query string and close the webviewti
Figure 4 depicts the sequence to obtain the access and refresh tokens
Figure 4 ining the access and refresh tokens Sequence for obta
Refer to the following screenshots on how authorization codeto obtain an
HTTP Get to the above URL in a web page and the logon page opens
Figure 5 Logon page
Enter the username and password
Figure 6 Entering user credentials
The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning httpsltltREDIRECT_URLgtgtcode=ltltoauth_autho ation_coderiz gtgt
The code oauth_authorization_code is reused at the next step to trade it for the access en and refresh tokentok
En Point URL to Access an Access Tokend-
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoau 2code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwABampgrant_type=authorization_cothdeampclient_id=MobileAppV1ampredirect_uri=ltgt
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code
Access token and refresh tokens are returned as JSON
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
1 2 3
Clients ConfiguredFollowing are the clients configured in PingFederate
Client Id Component Grant Types Supported
Pl0QC2Y1fAxX57V5K2uFcarVjDbflN SocialIDM Resource owner password credentials Grant type
pingfederate PingFederate Resource owner password credentials Grant type
axway_rs AxWay urnpingidentitycomoauth2grant_typevalidate_bearer
lS9qHlAEZwY4pSC4fIucAkzdemcaF8 NCR Mobile Ordering Mobile App authorization_code
6BE789472A038F0292AE1BD022434A NCR Mobile Ordering Resource Server urnpingidentitycomoauth2grant_typevalidate_bearer
MobileAppV1 Chick-fil-A Flag Ship Mobile App authorization_code
W6K5MVJSpEIsiIxmdO7KrtZKZXtgch Chick-fil-A Testing Team Resource owner password credentials Grant type
OAuth 20 Integration
Introduction
Chick-fil-A Inc is engaged in a multi-year multi-phased project to build a Customer Identity Management System to centralize the functionality ofauthentication authorization and user management The integrating service providers can leverage this system for the following
AuthenticationAuthorization to access an HTTP ServiceRESTful API to access users identity profile based on authorization granted as part of the step 2
The document describes integration capabilities of Customer Identity Management System and to define the integration interfaces
Glossary
Term Definition
Resource server(API server)
The server that hosts the protected resources capable of accepting and responding to the protected resource requestsby using the access tokens
ClientApplication An application that makes the protected resource requests on behalf of the end user The term client does not implyany particular implementation characteristics for the application executes on a server a desktop orexample whetherother devices
Authorizationserver
The server that issues access tokens to the client after successfully authenticating the resource owner and obtainingauthorization
AuthorizationCodeAuthorizationToken
The authorization code is obtained by using an authorization server as an intermediary between the client and the enduser It is used to authenticate the client and grant the transmission of the access token This is the token thatauthorization server issues to the clients that can be swapped for an access token It has a very short lifetime since theswap must be performed immediately after users provide their authorization
Access Token A token required to access the resources protected by OAuth 20 The access token has an expiry time and is active for12 minutes
Refresh Token A token that the authorization server issues to clients and can be swapped for a brand new access token withoutrepeating the authorization process The refresh token has an expiry time and is active for 30 days
References
Reference Documentation
OAuth 20 Specification
Refer to this location for the final version of the specificationhttptoolsietforghtmlrfc6749
OAuth 20 Clients
Refer to this location to view OAuth 20 Clientshttpoauthnet2
OAuth 20 Development Tools
Tool Location
Chrome REST Client httpschromegooglecomwebstoredetailadvanced-rest-clienthgmloofddffdnphfgcellkdfbfbjeloohl=en-US
Firefox REST Client httpsaddonsmozillaorgen-USfirefoxaddonrestclient
Standards in Solution
OAuth 20
OAuth 20 is the Authorization standard used in this proposed solution As per RFC OAuth 20 authorization framework enables a third-partyapplication to obtain limited access to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction between theresource owner and the HTTP service or by allowing the third-party application to obtain access on its own behalf In simple terms OAuthprovides an API based security solution that does not require customers to pass on their user name and password to the resource server
IntegrationRefer to Figure 1 that depicts the integration process
Figure 1 Integration process
Registration
All applications that can access a Chick-fil-A APIs must be registered The registration is currently an offline process The result of this registrationprocess is a client ID and client secret shared between Chick-fil-A and integrating application The set of variable values is based on the type ofapplication that you are building For example a JavaScript application does not require a secret but a web server application requires
Integration With OAuth Authorization Server
To begin by using OAuth 20 the integrating client requires the following details
The URL of the service being accessedThe Auth scope which is a string that defines the specific type of access app is asking forA client ID and client secret which are strings that identify the app to the service OAuth 20 requires client registration that limits the APIaccess to register the clients only Within Customer Identity Management System client_id and client_secret are required for clientauthentication The service integration team must obtain these strings directly from the Customer Identity Management team
Environment
Specific End-Point URLs
1 2 3 4
Environment End-point URLs
Dev httpslogindevcrndevchick-fil-acom
Stage httpsloginqacrndevchick-fil-acom
Prod httpsloginchick-fil-acom
Note Use a dynamic configuration file to access these URLs The service URLs may change as part of the service upgrade
OAuth 20 End-Points
Use End-point Description
Authorizationcode
asauthorizationoauth2 Used by the OAuth AS to interact directly with the resource owners authenticate them and obtainauthorization
Accesstoken
astokenoauth2 Used by the client to obtain an access token and possibly a refresh token by presenting itsauthorization grantrefresh token This endpoint accepts only the HTTP POST method
TokenValidation
astokenoauth2 Used by the client to validate an access token
Token Info oauth2tokeninfo Getting token information
OAuth Grants
There are four different types of OAuth 20 grants they are
Authorization code grantImplicit grantResource owner password credentials grantClient cre grantdentials
The OAuth ch is used in this solution is an Authorization code grant The scenarios explained below are based on Authorization codeGrant whigrant
OAuth 20 Authorization Grant
The authorization code grant starts with the client redirecting the resource owners user-agent to ede orization service After the PingF rate authauthe icating the re ource owner and obtaining the resource owners authorization PingFederate redirects the resource owners user-agent backnt sto the cl nt wit an authorization code that the client uses to request the access token ie hFigure 2 outlines a successful process from the initial client redirection to the client accessing t protected resourche e
Figu e 2 Aut rization code grant sequencer ho
Scopes Within the Solution
The authorization scope is a string that defines the specific type of access the application is asking for The scope in this solution is usually aservice URI The Chick-fil-A authorization server does not explicitly prompt the end user for authorization The authorization server currentlygrants access to the following scopes where each scope has corresponding list of user profile attributes accessible as part of the token i ormationfn service call
Scope User Attributes Accessible
TODO
TODO
Integration With OAuth Resource Server
REST Web Services Security
All the incoming requests are authenticated based on OAuth 20Unless specified all the REST web services must send a valid OAuth 20 access token in the header
Including OAuth Access Token (REST Web Services)
For all the REST Web Service the OAuth Access token must be included in the HTTP header The name and format of the HTTP header is asfollows
Name Value
Header Name Authorization
Header Value Bearer ltltOAuth Access Tokengtgt
Example Authorization Bearer efa8c03f-9557-422a-8d75-284e3e86a1c4
Using Refresh Token
A refresh token is a string that represents the authorization granted to the client by the resource owner The string is usually not visible to theclient The token denotes an identifier used to retrieve the authorization information Unlike access tokens refresh tokens are intended for useonly with the authorization servers and are never sent to the resource servers
Figure 3 Refreshing an expired access token
Sample Use Cases and ScreenshotsThe given sample use cases and screenshots are about how to obtain an OAuth access token based on authorization_code grant type Forcomplete end point details please refer to OAuth 20 Integration Endpoints Sample Requests and Sample Responses
End-Point URL to Authorize
HTTP (GET)httpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=MobileAppV1ampscope=sessionidmeampredirect_uri=httplocalhost9090redirectltltREDIRECT_URLgtgt is the final URL which the webpage is redirected upon successful aut ntication and authorization The mobile app musthedetect the URL retrieve the authoriza on code from the query string and close the webviewti
Figure 4 depicts the sequence to obtain the access and refresh tokens
Figure 4 ining the access and refresh tokens Sequence for obta
Refer to the following screenshots on how authorization codeto obtain an
HTTP Get to the above URL in a web page and the logon page opens
Figure 5 Logon page
Enter the username and password
Figure 6 Entering user credentials
The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning httpsltltREDIRECT_URLgtgtcode=ltltoauth_autho ation_coderiz gtgt
The code oauth_authorization_code is reused at the next step to trade it for the access en and refresh tokentok
En Point URL to Access an Access Tokend-
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoau 2code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwABampgrant_type=authorization_cothdeampclient_id=MobileAppV1ampredirect_uri=ltgt
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code
Access token and refresh tokens are returned as JSON
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
OAuth 20 Clients
Refer to this location to view OAuth 20 Clientshttpoauthnet2
OAuth 20 Development Tools
Tool Location
Chrome REST Client httpschromegooglecomwebstoredetailadvanced-rest-clienthgmloofddffdnphfgcellkdfbfbjeloohl=en-US
Firefox REST Client httpsaddonsmozillaorgen-USfirefoxaddonrestclient
Standards in Solution
OAuth 20
OAuth 20 is the Authorization standard used in this proposed solution As per RFC OAuth 20 authorization framework enables a third-partyapplication to obtain limited access to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction between theresource owner and the HTTP service or by allowing the third-party application to obtain access on its own behalf In simple terms OAuthprovides an API based security solution that does not require customers to pass on their user name and password to the resource server
IntegrationRefer to Figure 1 that depicts the integration process
Figure 1 Integration process
Registration
All applications that can access a Chick-fil-A APIs must be registered The registration is currently an offline process The result of this registrationprocess is a client ID and client secret shared between Chick-fil-A and integrating application The set of variable values is based on the type ofapplication that you are building For example a JavaScript application does not require a secret but a web server application requires
Integration With OAuth Authorization Server
To begin by using OAuth 20 the integrating client requires the following details
The URL of the service being accessedThe Auth scope which is a string that defines the specific type of access app is asking forA client ID and client secret which are strings that identify the app to the service OAuth 20 requires client registration that limits the APIaccess to register the clients only Within Customer Identity Management System client_id and client_secret are required for clientauthentication The service integration team must obtain these strings directly from the Customer Identity Management team
Environment
Specific End-Point URLs
1 2 3 4
Environment End-point URLs
Dev httpslogindevcrndevchick-fil-acom
Stage httpsloginqacrndevchick-fil-acom
Prod httpsloginchick-fil-acom
Note Use a dynamic configuration file to access these URLs The service URLs may change as part of the service upgrade
OAuth 20 End-Points
Use End-point Description
Authorizationcode
asauthorizationoauth2 Used by the OAuth AS to interact directly with the resource owners authenticate them and obtainauthorization
Accesstoken
astokenoauth2 Used by the client to obtain an access token and possibly a refresh token by presenting itsauthorization grantrefresh token This endpoint accepts only the HTTP POST method
TokenValidation
astokenoauth2 Used by the client to validate an access token
Token Info oauth2tokeninfo Getting token information
OAuth Grants
There are four different types of OAuth 20 grants they are
Authorization code grantImplicit grantResource owner password credentials grantClient cre grantdentials
The OAuth ch is used in this solution is an Authorization code grant The scenarios explained below are based on Authorization codeGrant whigrant
OAuth 20 Authorization Grant
The authorization code grant starts with the client redirecting the resource owners user-agent to ede orization service After the PingF rate authauthe icating the re ource owner and obtaining the resource owners authorization PingFederate redirects the resource owners user-agent backnt sto the cl nt wit an authorization code that the client uses to request the access token ie hFigure 2 outlines a successful process from the initial client redirection to the client accessing t protected resourche e
Figu e 2 Aut rization code grant sequencer ho
Scopes Within the Solution
The authorization scope is a string that defines the specific type of access the application is asking for The scope in this solution is usually aservice URI The Chick-fil-A authorization server does not explicitly prompt the end user for authorization The authorization server currentlygrants access to the following scopes where each scope has corresponding list of user profile attributes accessible as part of the token i ormationfn service call
Scope User Attributes Accessible
TODO
TODO
Integration With OAuth Resource Server
REST Web Services Security
All the incoming requests are authenticated based on OAuth 20Unless specified all the REST web services must send a valid OAuth 20 access token in the header
Including OAuth Access Token (REST Web Services)
For all the REST Web Service the OAuth Access token must be included in the HTTP header The name and format of the HTTP header is asfollows
Name Value
Header Name Authorization
Header Value Bearer ltltOAuth Access Tokengtgt
Example Authorization Bearer efa8c03f-9557-422a-8d75-284e3e86a1c4
Using Refresh Token
A refresh token is a string that represents the authorization granted to the client by the resource owner The string is usually not visible to theclient The token denotes an identifier used to retrieve the authorization information Unlike access tokens refresh tokens are intended for useonly with the authorization servers and are never sent to the resource servers
Figure 3 Refreshing an expired access token
Sample Use Cases and ScreenshotsThe given sample use cases and screenshots are about how to obtain an OAuth access token based on authorization_code grant type Forcomplete end point details please refer to OAuth 20 Integration Endpoints Sample Requests and Sample Responses
End-Point URL to Authorize
HTTP (GET)httpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=MobileAppV1ampscope=sessionidmeampredirect_uri=httplocalhost9090redirectltltREDIRECT_URLgtgt is the final URL which the webpage is redirected upon successful aut ntication and authorization The mobile app musthedetect the URL retrieve the authoriza on code from the query string and close the webviewti
Figure 4 depicts the sequence to obtain the access and refresh tokens
Figure 4 ining the access and refresh tokens Sequence for obta
Refer to the following screenshots on how authorization codeto obtain an
HTTP Get to the above URL in a web page and the logon page opens
Figure 5 Logon page
Enter the username and password
Figure 6 Entering user credentials
The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning httpsltltREDIRECT_URLgtgtcode=ltltoauth_autho ation_coderiz gtgt
The code oauth_authorization_code is reused at the next step to trade it for the access en and refresh tokentok
En Point URL to Access an Access Tokend-
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoau 2code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwABampgrant_type=authorization_cothdeampclient_id=MobileAppV1ampredirect_uri=ltgt
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code
Access token and refresh tokens are returned as JSON
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
1 2 3 4
Environment End-point URLs
Dev httpslogindevcrndevchick-fil-acom
Stage httpsloginqacrndevchick-fil-acom
Prod httpsloginchick-fil-acom
Note Use a dynamic configuration file to access these URLs The service URLs may change as part of the service upgrade
OAuth 20 End-Points
Use End-point Description
Authorizationcode
asauthorizationoauth2 Used by the OAuth AS to interact directly with the resource owners authenticate them and obtainauthorization
Accesstoken
astokenoauth2 Used by the client to obtain an access token and possibly a refresh token by presenting itsauthorization grantrefresh token This endpoint accepts only the HTTP POST method
TokenValidation
astokenoauth2 Used by the client to validate an access token
Token Info oauth2tokeninfo Getting token information
OAuth Grants
There are four different types of OAuth 20 grants they are
Authorization code grantImplicit grantResource owner password credentials grantClient cre grantdentials
The OAuth ch is used in this solution is an Authorization code grant The scenarios explained below are based on Authorization codeGrant whigrant
OAuth 20 Authorization Grant
The authorization code grant starts with the client redirecting the resource owners user-agent to ede orization service After the PingF rate authauthe icating the re ource owner and obtaining the resource owners authorization PingFederate redirects the resource owners user-agent backnt sto the cl nt wit an authorization code that the client uses to request the access token ie hFigure 2 outlines a successful process from the initial client redirection to the client accessing t protected resourche e
Figu e 2 Aut rization code grant sequencer ho
Scopes Within the Solution
The authorization scope is a string that defines the specific type of access the application is asking for The scope in this solution is usually aservice URI The Chick-fil-A authorization server does not explicitly prompt the end user for authorization The authorization server currentlygrants access to the following scopes where each scope has corresponding list of user profile attributes accessible as part of the token i ormationfn service call
Scope User Attributes Accessible
TODO
TODO
Integration With OAuth Resource Server
REST Web Services Security
All the incoming requests are authenticated based on OAuth 20Unless specified all the REST web services must send a valid OAuth 20 access token in the header
Including OAuth Access Token (REST Web Services)
For all the REST Web Service the OAuth Access token must be included in the HTTP header The name and format of the HTTP header is asfollows
Name Value
Header Name Authorization
Header Value Bearer ltltOAuth Access Tokengtgt
Example Authorization Bearer efa8c03f-9557-422a-8d75-284e3e86a1c4
Using Refresh Token
A refresh token is a string that represents the authorization granted to the client by the resource owner The string is usually not visible to theclient The token denotes an identifier used to retrieve the authorization information Unlike access tokens refresh tokens are intended for useonly with the authorization servers and are never sent to the resource servers
Figure 3 Refreshing an expired access token
Sample Use Cases and ScreenshotsThe given sample use cases and screenshots are about how to obtain an OAuth access token based on authorization_code grant type Forcomplete end point details please refer to OAuth 20 Integration Endpoints Sample Requests and Sample Responses
End-Point URL to Authorize
HTTP (GET)httpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=MobileAppV1ampscope=sessionidmeampredirect_uri=httplocalhost9090redirectltltREDIRECT_URLgtgt is the final URL which the webpage is redirected upon successful aut ntication and authorization The mobile app musthedetect the URL retrieve the authoriza on code from the query string and close the webviewti
Figure 4 depicts the sequence to obtain the access and refresh tokens
Figure 4 ining the access and refresh tokens Sequence for obta
Refer to the following screenshots on how authorization codeto obtain an
HTTP Get to the above URL in a web page and the logon page opens
Figure 5 Logon page
Enter the username and password
Figure 6 Entering user credentials
The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning httpsltltREDIRECT_URLgtgtcode=ltltoauth_autho ation_coderiz gtgt
The code oauth_authorization_code is reused at the next step to trade it for the access en and refresh tokentok
En Point URL to Access an Access Tokend-
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoau 2code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwABampgrant_type=authorization_cothdeampclient_id=MobileAppV1ampredirect_uri=ltgt
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code
Access token and refresh tokens are returned as JSON
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Figu e 2 Aut rization code grant sequencer ho
Scopes Within the Solution
The authorization scope is a string that defines the specific type of access the application is asking for The scope in this solution is usually aservice URI The Chick-fil-A authorization server does not explicitly prompt the end user for authorization The authorization server currentlygrants access to the following scopes where each scope has corresponding list of user profile attributes accessible as part of the token i ormationfn service call
Scope User Attributes Accessible
TODO
TODO
Integration With OAuth Resource Server
REST Web Services Security
All the incoming requests are authenticated based on OAuth 20Unless specified all the REST web services must send a valid OAuth 20 access token in the header
Including OAuth Access Token (REST Web Services)
For all the REST Web Service the OAuth Access token must be included in the HTTP header The name and format of the HTTP header is asfollows
Name Value
Header Name Authorization
Header Value Bearer ltltOAuth Access Tokengtgt
Example Authorization Bearer efa8c03f-9557-422a-8d75-284e3e86a1c4
Using Refresh Token
A refresh token is a string that represents the authorization granted to the client by the resource owner The string is usually not visible to theclient The token denotes an identifier used to retrieve the authorization information Unlike access tokens refresh tokens are intended for useonly with the authorization servers and are never sent to the resource servers
Figure 3 Refreshing an expired access token
Sample Use Cases and ScreenshotsThe given sample use cases and screenshots are about how to obtain an OAuth access token based on authorization_code grant type Forcomplete end point details please refer to OAuth 20 Integration Endpoints Sample Requests and Sample Responses
End-Point URL to Authorize
HTTP (GET)httpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=MobileAppV1ampscope=sessionidmeampredirect_uri=httplocalhost9090redirectltltREDIRECT_URLgtgt is the final URL which the webpage is redirected upon successful aut ntication and authorization The mobile app musthedetect the URL retrieve the authoriza on code from the query string and close the webviewti
Figure 4 depicts the sequence to obtain the access and refresh tokens
Figure 4 ining the access and refresh tokens Sequence for obta
Refer to the following screenshots on how authorization codeto obtain an
HTTP Get to the above URL in a web page and the logon page opens
Figure 5 Logon page
Enter the username and password
Figure 6 Entering user credentials
The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning httpsltltREDIRECT_URLgtgtcode=ltltoauth_autho ation_coderiz gtgt
The code oauth_authorization_code is reused at the next step to trade it for the access en and refresh tokentok
En Point URL to Access an Access Tokend-
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoau 2code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwABampgrant_type=authorization_cothdeampclient_id=MobileAppV1ampredirect_uri=ltgt
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code
Access token and refresh tokens are returned as JSON
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Name Value
Header Name Authorization
Header Value Bearer ltltOAuth Access Tokengtgt
Example Authorization Bearer efa8c03f-9557-422a-8d75-284e3e86a1c4
Using Refresh Token
A refresh token is a string that represents the authorization granted to the client by the resource owner The string is usually not visible to theclient The token denotes an identifier used to retrieve the authorization information Unlike access tokens refresh tokens are intended for useonly with the authorization servers and are never sent to the resource servers
Figure 3 Refreshing an expired access token
Sample Use Cases and ScreenshotsThe given sample use cases and screenshots are about how to obtain an OAuth access token based on authorization_code grant type Forcomplete end point details please refer to OAuth 20 Integration Endpoints Sample Requests and Sample Responses
End-Point URL to Authorize
HTTP (GET)httpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=MobileAppV1ampscope=sessionidmeampredirect_uri=httplocalhost9090redirectltltREDIRECT_URLgtgt is the final URL which the webpage is redirected upon successful aut ntication and authorization The mobile app musthedetect the URL retrieve the authoriza on code from the query string and close the webviewti
Figure 4 depicts the sequence to obtain the access and refresh tokens
Figure 4 ining the access and refresh tokens Sequence for obta
Refer to the following screenshots on how authorization codeto obtain an
HTTP Get to the above URL in a web page and the logon page opens
Figure 5 Logon page
Enter the username and password
Figure 6 Entering user credentials
The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning httpsltltREDIRECT_URLgtgtcode=ltltoauth_autho ation_coderiz gtgt
The code oauth_authorization_code is reused at the next step to trade it for the access en and refresh tokentok
En Point URL to Access an Access Tokend-
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoau 2code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwABampgrant_type=authorization_cothdeampclient_id=MobileAppV1ampredirect_uri=ltgt
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code
Access token and refresh tokens are returned as JSON
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Figure 4 ining the access and refresh tokens Sequence for obta
Refer to the following screenshots on how authorization codeto obtain an
HTTP Get to the above URL in a web page and the logon page opens
Figure 5 Logon page
Enter the username and password
Figure 6 Entering user credentials
The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning httpsltltREDIRECT_URLgtgtcode=ltltoauth_autho ation_coderiz gtgt
The code oauth_authorization_code is reused at the next step to trade it for the access en and refresh tokentok
En Point URL to Access an Access Tokend-
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoau 2code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwABampgrant_type=authorization_cothdeampclient_id=MobileAppV1ampredirect_uri=ltgt
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code
Access token and refresh tokens are returned as JSON
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Figure 5 Logon page
Enter the username and password
Figure 6 Entering user credentials
The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning httpsltltREDIRECT_URLgtgtcode=ltltoauth_autho ation_coderiz gtgt
The code oauth_authorization_code is reused at the next step to trade it for the access en and refresh tokentok
En Point URL to Access an Access Tokend-
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoau 2code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwABampgrant_type=authorization_cothdeampclient_id=MobileAppV1ampredirect_uri=ltgt
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code
Access token and refresh tokens are returned as JSON
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Figure 6 Entering user credentials
The authorization code is sent through HTTP 302 on the redirect URL specified at the beginning httpsltltREDIRECT_URLgtgtcode=ltltoauth_autho ation_coderiz gtgt
The code oauth_authorization_code is reused at the next step to trade it for the access en and refresh tokentok
En Point URL to Access an Access Tokend-
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoau 2code=LOzI6nS3dXoA5h2rpsNmG1Xft1CY-rvgcF4mmwABampgrant_type=authorization_cothdeampclient_id=MobileAppV1ampredirect_uri=ltgt
Refer to the following screenshot on how to obtain the access token and refresh token by using the authorization code
Access token and refresh tokens are returned as JSON
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Figure 7End-Point URL to access an access token
Endpoint for Obtaining Access Toke Based on Refresh Token
HTTP (POST)httpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Getting Token info
HTTP (GET)httpslogindevcrndevchick-fil-acomoauth2tokeninfoaccess_token=ltltACCESS_TOKENgtgt
A successful sample response looks like
Access token based on Refresh Token Response
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
OAuth 20 Integration Endpoints Sample Requests and SampleResponses
End Points for Authorization Code Grant Type
To obtain Authorization code POSThttpslogindevcrndevchick-fil-acomasauthorizationoauth2pfidpadapterid=HtmlFormCampresponse_type=codeampclient_id=ltltclient_idgtgtampredirect_uri=httplocalhost9090redirect
To obtain OAuth access token POSThttpslogindevcrndevchick-fil-acomastokenoauth2code=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=ltltclie
= nt_idgtgtampredirect_uri httplocalhost9090redirect
Endpoint for Resouce Owner Password Crendetials Grant Type
To obtain OAuth access token POSThttpsloginqacrndevchick-fil-acomastokenoauth2grant_type=passwordampclient_id=ltltclient_idgtgtampusername=ltltcfa_mail_idgtgtamppassword=ltltcfa_passwordgtgtampredirect_uri=httplocalhost9090redirect
End Point for Granturnpingidentitycomoauth2grant_typevalidate_bearerTypeValidating an Access Token
Access the following URL by replacing the ltltaccess_tokengtgt with the appropriate value
HTTP POST with basic authentication (Oauth client ID as and client secret as )user name user passwordhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
End Point for Client Credentials Grant Type
To obtain an access token go to the following URL with HTTP POST and replace ltltclient_idgtgt and ltltclient_secretgtgt with appropriatevalues POSThttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=client_credentialsampclient_id=ltltClient_idgtgtampclient_secret=ltltclient_
secretgtgt
Obtain an Access Token With Grant Type as Authorization Code Refer to httpsalmcfadevelopnetwikidisplayCRNIDNADOAuth+20+IntegrationOAuth20Integration-_Toc376440359
Validating an Access Token To validate an access token go to the following URL with HTTP POST + HTTP basic of a client Replaceauth
Access token based on Refresh Token Response
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
the ltltaccess_tokengtgt with the valid access tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=urnpingidentitycomoauth2grant_typevalidate_beareramptoken=ltltaccess_tokengtgt
A Success Response gives the following output
status code 200Http Response body
scope token_type urnpingidentitycomoauth2validated_token expires_in 238 client_id MobileAppV1 access_token uid CFAID-Test1 mail testuser1democom
The success response also provides the client_id This client_id refers to the client used to obtain the access token In case of Error
HTTP status code 400 Response body
errorinvalid_granterror_descriptiontoken not found expired orinvalid
In case client authentication fails HTTP status code 400 Response body
error invalid_client error_description urnpingidentitycomoauth2grant_typevalidate_bearerrequires client authentication
Endpoint for Obtaining Access Token Based on Refresh Token
Access the following URL replacing ltltRefresh_Tokengtgt with the appropriate refresh tokenhttpslogindevcrndevchick-fil-acomastokenoauth2grant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
Example curl command is curl --request POST --datagrant_type=refresh_tokenamprefresh_token=RAuRjJNmDsd457KofKVwj9eaH4mJlBL7u24OyBIK2V
A successful sample response looks like
Token Validation Success Response
Token Validation Failure Response
Token Validation Response - In case Client authentication fails
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
1
2
token_type Bearer expires_in 599 refresh_token9L7QHxiSNNux9YQ1Es4skWzPLG4RN9CbF3d0Jmui2d access_tokenTW6kHy0TmtknIMitAvmcChT3NgDs
Revoking OAuth Token
Accessing the following URL provides a list OAuth tokens generated for user
httpslogindevcrndevchick-fil-acomasoauth_access_grantsping
Authentication is required to access the pageNote
For REST API access the following URL to revoke an OAuth Token
httpslogindevcrndevchick-fil-acomasrevoke_tokenoauth2token=ltltrefresh_tokengtgtampclient_id=ltltclient_idgtgtamptoken_type_hint=refresh_token
Reference httptoolsietforghtmlrfc7009
PingFederate SAML Vs OpenTokenRefer to the following table to analyze the pros and cons to select either SAML or OpenToekn for implementing Single Sign-on
Process SAML OpenToken
1 Step UpAuthentication
Supports Step Up Authenticationusing Authentication Levelcontext
Does not support
2 Passive Loginsupport
Yes No
3 Security Symmetric Encryption + Digitalsignatures
Symmetric Encryption
4 OAuth 20AuthenticationLevel basedsupport
Yes No
5 Is it countableas a connection
Yes
If two adapters in a SAMLapplication is configured it is stillcounted as one connection
No
But if adapter-to-adapter mapping is performed it is counted as connection Forexample if the following adapter mapping is performed Facebook raquo OpenToken andHTMLForm Adapter OpenToken it is counted as tworaquo
6 ProgrammaticLogin
PingFederate and CloudHSM IntegrationPerform the following steps to integrate PingFederate and CloudHSM The integration is tested with PingFederate 71R2 and PingFederate 71R3along with CloudHSM client 531 The following PF_HOME represents apps pingfederate_latestpingfederate pingfederate
Install and configure client and register with a partition if it is not already there To install CloudHSM CloudHSM follow the giinstructionsven at
Once the Network Trust Link (NTL) by running the command The output looks asCloudHSM configuration is completed verify verifyvtlshown belowThe following Luna SA SlotsPartitions were found
Slot Serial Label
Access token based on Refresh Token Response
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
2
3
4
5
6
7
8
9
10
1 156664020 qa-crnidm-mgmt
Copy clients JSP lib directory content to if the following files so and doCloudHSM JAVA_HOMEjrelibext libLunaAPI LunaProvider jarnot existMake sure that all users have execution permission on the file If required run the following command to provide permissionlibLunaAPIto all the users
chmod o+x $JAVA_HOMEjrelibextlibLunaAPIso
Add the following line to Java security providers by editing the following file $JAVA_HOMEjrelibsecurity securityjava
securityprovider10=comsafenetinclunaproviderLunaProvider
Go to the directory and delete JKS files if there are anyPF_HOMEserverdefaultdata
cd appspingfederatepingfederate_latestpingfederateserverdefaultdatarm -f jks
Edit file present in directory as shown belowhivemodulexml PF_HOMEserverdefaultdata
Change
lt class= crypto SunJCEManagergt to ltconstruct class= crypto LunaJCEManager5gtconstruct compingidentity compingidentity
and
lt class= crypto CertificateServiceImplgt to ltconstruct class= crypto LunaCertificateServiceIconstruct compingidentity compingidentity mpl5gt
Edit file present in as shown belowrunproperties PF_HOMEbinrunpropertiesfrom pfhsmmode=OFF to pfhsmmode=LUNA
Now run the following commands to store the partition passwordCloudHSM
Sh appspingfederatepingfederate_latestpingfederatebinhsmpasssh
Output will look like following
PingFederate Password Changer --------------------------------------------WARNING Password file does not existappspingfederatepingfederate-710-R3pingfederatebinserverdefaultdatahsmpasswdtxt
Password ltltEnter cloudhsm partition password heregtgtFile hsmpasswdtxt has been created
Once all the above steps are completed restart the PingFederate server Repeat the same for all the nodes present in cluster Make surethat all the nodes belong to the same partitionCloudHSM
PingFederate OAuth Vs OpenAM OAuthThe following table describes the differences between the OAuth implementation for PingFederate and OpenAM
OpenAM
Authorizationcode
oauth2authorize realm=external
(HTTP POST)Example
httpsdevaccountschick-fil-acomamserveroauth2authorizerealm=externalampclient_id=MobileAppV1ampresponse_type=codeampscope=sessionidmeampredirect_uri=ltltREDIRECT_URLgtgt
Accesstoken fromauthorizationcode
oauth2access_token realm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampcode=ltltauthorization_codegtgtampgrant_type=authorization_codeampclient_id=MobileAppV1ampredirect_uri=ltltREDIRECT_URLgtgt
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Json payloadreturnedfrom AS for authorizationcode granttype
expires_in 719 token_type Bearer refresh_token 12af4ae9-7e07-4df3-97d3-779e8c2c8f47 access_token a26d8690-24e7-4f96-baf2-0921fd997374
Accesstoken fromrefresh token
oauth2access_tokenrealm=external
Example (HTTP POST)
httpsdevaccountschick-fil-acomamserveroauth2access_tokenrealm=externalampgrant_type=refresh_tokenamprefresh_token=ltltREFRESH_TOKENgtgt
payloadJsonreturnedfrom AS forgettingaccess tokenin exchangeof a refreshtoken
scope confirmtxns giftcardme sessionidme userprofile expires_in 719 token_type Bearer access_token b8984cab-b8bd-4622-b15d-f0708b73de3b
Tokenvalidation
oauth2tokeninfo
Example HTTP GET
httpsdevaccountschick-fil-acomamserveroauth2tokeninfoaccess_token=ltltAccess-Tokengtgt
payloadJsonfor tokenvalidation
scope [ confirmtxns sessionidme giftcardme userprofile ] token_type Bearer expires_in 693 uid CFAID-BEWT6DAVE8 mail testuser1democom cn Test User1 realm external access_token 08857e6c-69ac-4e5d-957d-e1eb04f78d23
PingFederate TimeOut ValuesThe following table describes the timeout values for different components in PingFederate
Component Value
Local Login 60 minutes
Remember Me cookie 30 days
OAuth - authorization code 60 seconds
OAuth - access token 12 minutes
OAuth - Refresh Token 30 days
SocialIDM User Instructions
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
1 2 3 4
End Points
Environment URL
Dev httpsmydevcrndevchick-fil-acom
QA httpsmyqacrndevchick-fil-acom
Production TBD
Target URL
Name Dev
Registration httpsmydevcrndevchick-fil-acomsocialidm-webregistration
ProfileManagement
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ChangePassword
httpsmydevcrndevchick-fil-acomsocialidm-webprofile
ForgotPassword
httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme
DeactivateUserAccount
httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate
Note These user instructions are not standard and would change as per the features added to SocialIDM
The following modules are implemented in SocialIDM
RegistrationProfile ManagementChange PasswordDeactivate User Account
Important The following links are for development environment only
1 Registration
Go to to registercreate a user profile Once the user is registered ithttpsmydevcrndevchick-fil-acomsocialidm-webregistrationautomatically redirects you to the page showing two tabs viz and as shown belowProfile Management View Profile Change Password
Click to view your profile and click to change your profile password View Profile Change Password
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Figure ViewChange password page
Once you click any of the tabs you are redirected to the authentication page Enter your credentials to log on After successful logon ittakes you back to the SocialIDM requested operational page Now you can update your profile and change password
2 Profile Management
On profile management page you can view and update your profile if required
Go to to access your profile and is next redirected to the logon page Enter yourhttpsmydevcrndevchick-fil-acomsocialidm-webprofilecredentials to view and update your profile
3 Change Password
Go to to change your password You are again redirected to the logon page afterhttpsmydevcrndevchick-fil-acomsocialidm-webprofileaccessing the profile management link Logon takes you back to Profile management page The Change password page appears
Enter the current password new password and confirm password in the respective fields Any mismatch of character in the New and fields does not allow you to change your passwordPassword Confirm Password
4 Deactivate User Account
Go to httpsmydevcrndevchick-fil-acomsocialidm-webprofiledeactivate to deactivate your profile There are two options viz 1) Back toprofile and 2) Deactivate account
If you click you are redirected to your profileBack to profile
If you click the would be is deactivatedDeactivate account
Reset Password
A user can reset the password in two ways
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
By using OTPBy answering the challenge questions and answers
Note Only the registered and active users with a valid email can reset the password
Go to the httpsmydevcrndevchick-fil-acomsocialidm-webpwdresetgoto=httpsmydevcrndevchick-fil-acomsocialidm-webprofileme Res page opens as shown belowet Password
1 Enter your registered email address in the text box and click Email Search
Figure Resetting password
2 On successful verification of the email address you are redirected to the page Click Choose Reset Password Mode By One Time Passcode if you want to reset your password using the OTP or click if you want to reset your password by answering theBy Answering Questionschallenge questions and answers
Figure Password reset mode
3 If you click an OTP is sent to your mail address The following page appears Enter the one time passcode accountBy One Time Passcode password and confirm the password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Figure OTP
4 If you click the following page appears Enter the challenge question and answer account password and confirmBy Answering Questionsthe password Click You are redirected to the logon page with the message Password UpdatedChange Password
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Figure Challenge question and answer
You can log on with the reset password on the logon page
Figure Logon page
User Profile IntegrationThis section describes the end points to make REST web service calls to Directory Server through the AxWay API Server Client can use thisinterface to add update or authenticate a user profile This section also describes the necessary authentication mechanism required to accessthe interface
End Points
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Environment URL
Dev httpsprofileapidevcrndevchick-fil-acom
QA httpsprofileapiqacrndevchick-fil-acom
Production TBD
REST Web Services End Point URIs
User Management
Usage Resource Method
Add a user users20 POST
List users based on a criteria users20search POST
Get User Profile users20user_id GET
Update Partial User Profile users20user_id PATCH
Get ones own profile users20me GET
Update ones own User Profile users20me PATCH
Deactivate ones own account users20deactivateme POST
Deactivate users account users20deactivateuser_id POST
Link Ones own Account with Social Identity usersltltversiongtgtsociallinkme PATCH
Link users Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH
Unlink users Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH
Credential Management
In phase -1 release there are two types of credentials stored for a user The first is the users password and the other is the reset password andchallenge question-answers
Usage Resource Method
Change Credentials credentials10user_id POST
Change Own Credentials credentials me10 POST
List type of Credentials set for a user credentials user_id10 GET
SetUpdate ones own challenge question answers credentials challengeqa10 user_id PATCH
Validate ones own challenge question answers credentials challengeqa10 user_id POST
Delete ones own challenge question answers credentials challengeqa10 user_id DELETE
Obtain ones own OTP Code credentials10otpuser_id GET
REST Web Services Security ndash OAuth
Refer to for more detailsOAuth Integration Guide
Request Payload
Refer to for payloadJSON Schema
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Error Codes
The following error codes and messages are used in the integration process
General Exception
This section describes the status codes that are shared among all the services
StatusCode
HTTPCode
Error Message Comments
000 200 Successful Call is successful
401 401 Unauthorized The incoming HTTP Digest Authorization header is invalid
401 401 Unauthorized The incoming IP Address is invalid
400 400 Unrecognized Request The incoming JSON payload is not in the specified format
900 500 Datastore communicationerror
The server is unable to communicate with the back end datastore
901 500 Datastore authenticationerror
The server is unable to authenticate the back end datastore
902 500 Datastore authorizationerror
The server is unable to perform the requested operation because the service accountcredential does not have sufficient privilege against the datastore
903 500 System Error Unhandled error scenario
904 500 Authorization Servercommunication error
Unable to communicate the authorization server
905 500 Failed to load propertiesfrom S3
Unable to initialize properties from s3
Add User
Status Code HTTP Code Error Message Comments
110 500 Duplicate email address The given email address already exists in the datastore
111 500 Duplicate AList number The given AList number already exists in the datastore
114 500 Malformed Birthdate Invalid Birth date format
115 500 Duplicate Addresses The given address already exists in the datastore
116 500 Duplicate phoneNumbers The give phoneNumber already exists in the datastore
119 500 Duplicate IDP identifier IDP identifier is already registered
150 500 Password constraint not met Password constraint is not met
190 500 Insufficient privilege The user doesnt not have sufficient privilege to perform the operation
199 200 Add user partial success Error while writing to preference store
Get User Profile
Status Code CodeHTTP Error Message Comments
200 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
290 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
299 200 Get user partial success Error while reading from preference store
Update User Profile
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Status Code CodeHTTP Error Message Comments
600 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
610 500 Duplicate email address The given email address already exists in the datastore
611 500 Duplicate AList number AList number is already registered
614 500 Malformed Birthdate Invalid Birth date format
619 500 Duplicate IDP identifier IDP identifier is already registered
650 500 Password constraint not met Password constraint is not met
690 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
699 200 Update user partial success Error while writing to preference store
List of Users Based on a Criteria
Status Code CodeHTTP Error Message Comments
300 200 No users found for the criteria No users are found for the criteria
302 500 Missing Operand1 Operand1 is missing
303 500 Invalid Operand1 Invalid Operand1
304 500 Missing Operand2 Operand2 is missing
305 500 Invalid Operand1 Invalid Operand1
306 500 Invalid Operator Invalid Operator
390 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
399 200 Search user partial success Error while querying from preference store
Deactivate a users account
Status Code CodeHTTP Error Message Comments
800 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
890 500 Insufficient privilege The user does not not have the required privileges to perform the operation
LinkUnlink Account with Social Identity
Status Code CodeHTTP Error Message Comments
900 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
901 500 Invalid Identifier The give identifier does not exist in the datastore
990 500 Insufficient privilege The user does not not have the required privileges to perform the operation
Change Credentials
StatusCode
CodHTTPe
Error Message Comments
3000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
3001 500 Current password is invalid The current password in the payload does not match the password in thedatastore
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
3002 500 Password constraint not met Password constraint is not met
3003 500 Invalid challenge QAcredentials
Challenge questions and answers credentials are invalid
3004 500 Invalid OTP code OTP code is invalid
3005 500 Invalid credential type The provided credential type is not supported
3090 500 Insufficient privilege The user does not have required privileges to update the credential
List type of Credentials Set for a User
Status Code CodeHTTP Error Message Comments
5000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
5001 200 No credentials set No credentials are set
5090 500 Insufficient privilege The user does not not have the required privileges to perform the operation
SetUpdate Ones Own Challenge Question Answers
Status Code CodeHTTP Error Message Comments
6000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
6090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
Validate Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
7000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
7001 500 Invalid Challenge QuestionAnswers
The provided answers do not match the answers stored in the datastore
7090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Delete Ones Own Challenge Question Answers
StatusCode
CodHTTPe
Error Message Comments
8000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
8001 500 Challenge Question Answers does notexist
The provided challenge question answers do not exist in thedatastore
8090 500 Insufficient privilege The user does not not have the privileges to perform therequired operation
Obtain Ones Own OTP Code
Status Code CodeHTTP Error Message Comments
9000 500 Invalid CFA-UID The given CFA-UID does not exist in the datastore
9090 500 Insufficient privilege The user does not not have the privileges to perform the operationrequired
APIVersion=v3
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
User Management
Usage Resource Method Scope
Add a user usersltltversiongtgt POST users
List users based on a criteria usersltltversiongtgtsearch POST users
Get User Profile usersltltversiongtgtuser_id GET users
Update Partial User Profile usersltltversiongtgtuser_id PATCH users
List groups for a specified user usersltltversiongtgtuser_idgroups GET users
Get ones own profile usersltltversiongtgtme GET usersme users
Get ones group association usersltltversiongtgtmegroups GET usersme users
Update ones own User Profile usersltltversiongtgtme PATCH usersme users
Deactivate users account usersltltversiongtgt user_iddeactivate POST users
Deactivate accountOnes own usersltltversiongtgtdeactivateme POST usersme users
Link Account with Social IdentityOnes own usersltltversiongtgtsociallinkme PATCH usersme users
Link Account with Social Identity usersltltversiongtgtsociallinkuser_id PATCH users
Unlink Ones own Account with Social Identity usersltltversiongtgtsocialunlinkme PATCH usersme users
Unlink Account with Social Identity usersltltversiongtgtsocialunlinkuser_id PATCH users
Group Management
Usage Resource Method
Add a group groupsltltversiongtgt POST
List groups based on a criteria groupsltltversiongtgt GET
Get Group Information groupsltltversiongtgtgroup_id GET
Update Partial Group Parameters groupsltltversiongtgtgroup_id PATCH
List the users in a specified group groupsltltversiongtgtgroup_idusers GET
Add a user to a specified group groupsltltversiongtgtgroup_idusersuser_id PUT
Remove a user from a group groupsltltversiongtgtgroup_idusersuser_id DELETE
Validate that a user is in a group groupsltltversiongtgtgroup_idusersuser_id HEAD
Credential ManagementIn phase -1 release there are two types of credentials stored for a use First being users password and other being password reset ndash challengequestion answers
Usage Resource Method Scope
Change Credentials credentialsltltversiongtgtuser_id POST credentials
Change Own Credentials credentialsltltversiongtgtme POST credentialsme
List type of Credentials set for a user credentialsltltversiongtgtuser_id GET credentials
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqa PATCH credentials
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqa POST credentials
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqa DELETE credentials
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET credentials
Get challenge questions credentialsltltversiongtgtchallengeqalang GET credentials
User Profile Management APIs
Add User ProfileThis section defines the APIs available for Adding a user
User Management API Add a user
Usage Resource Method
Add a user usersltltversiongtgt POST
Sample User Profile Creation
Add a User
Request
POSTusers20
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success uid CFAID-Z3FTVS5CS7FL6309
Get User ProfileThis section defines the APIs available for getting a user
User Management API Get a user
Usage Resource Method
Get a user profile usersltltversiongtgtuser_id GET
Get ones own profile usersltltversiongtgtme GET
Sample User Profile Retrival
Get a User
Request
GETusers20CFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Get ones own profile
Request
GETusers20me
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Response
statusCode 000 statusMessage success userProfile uid CFAID-Z3FTVS5CS7FL6309 socialConnections [ idp google identifier sampleuser idp facebook identifier sampleuser ] name familyName Sample givenName User displayName Sample User phoneNumbers [ value +1 98989898989 type Mobile value +1 6767676767 type Home ] emails [ primary true value sampleusergmailcom primary false value sampleuseryahoocom ] systemAttributes [] extendedAttributes [ termsOfUse true ageRange 25-30 ] addresses []
Update User ProfileThis section defines the APIs available for updating a user
User Management API Update a user
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Usage Resource Method
Update a user usersltltversiongtgtuser_id PATCH
Update ones own profile usersltltversiongtgtme PATCH
Sample User Profile Update
Update a User
Request
PATCHusers20CFAID-ABCDEFGHIJ123456
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Update ones own profile
Request
PATCHusers20me
SampleAddUpdateUserjson
Response
statusCode 000 statusMessage success
Search UsersThis section defines the APIs available for search users
User Management API Add a user
Usage Resource Method
Search users usersltltversiongtgtsearch POST
Supported Logical Operator
Operator Syntax Description
AND All condition must be met
OR One of the conditions must be met
NOT Any entries that doesnt meet the condition
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Supported Operator
Operator Syntax Description
EQ The two operands must be equal
GE The result must be great than or equal to operand2
LE The result must be less than or equal to operand2
APPROX The result must be approximately equal to operand2
Sample User Profile Search
Search Users based on given name AND display name
The below example uses the logical operator AND It will search for givenName=TK AND displayName startsWith TK is a wildcard symbolthat allows starts with search
Request
POSTusers20search
logicalOperatorAND operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1displayName operand2TK ]
Response
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
statusCode [ 000 success ] searchResultSize 12 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Search Users based on given name OR email
The below example uses the logical operator OR It will search for givenName=TK OR email= than-kharchinquberasolutionscom
Request
POSTusers20search
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
logicalOperatorOR operands[ operatorEQ operand1givenName operand2TK operatorEQ operand1email operand2than-kharchinquberasolutionscom ]
Response
statusCode [ 000 success ] searchResultSize 2 searchResult [ uid CFAID-TKTesting1 socialConnections [] name familyName CHIN givenName TK displayName TK Chin phoneNumbers [] emails [] systemAttributes [] extendedAttributes [] addresses [] uid CFAID-TKTesting2 uid CFAID-TKTesting3 ]
Deactivate an accountThis section defines the APIs available for deactivating a user
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
User Management API Get a user
Usage Resource Method
Deactivate a user profile usersltltversiongtgtdeactivateuser_id POST
Deactivate ones own profile usersltltversiongtgtdeactivateme POST
Sample User Profile Deactivation
Deactivate a User
Request
POSTusers20deactivateCFAID-ABCDEFGHIJ123456
Response
statusCode 000 statusMessage success
Deactivate ones own profile
Request
POSTusers20deactivateme
Response
statusCode 000 statusMessage success
LinkUnlink Account
Credential Management APIsRefer to the following sections that describe the usage of the Credential Management APIs
Credential Management Admin Password ResetCredential Management Change PasswordCredential Management KBACredential Management OTPCredential Management Get Credential
Credential Management Admin Password ResetThis section defines the APIs available for Admin password reset
Credential Management API Admin Password Reset
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Sample Password Reset Call
Change Credentials - Admin Password Reset
This API only works if the user has not set the password yetNote
Request
POSTcredentials10user_id
type Password fields [ fieldNamepassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Change PasswordThis section defines the APIs available for Change Password
Credential Management API - Change Password
Usage Resource Method
Change credentials credentialsltltversiongtgtuser_id POST
Change own credentials credentialsltltversiongtgtme POST
Change Credentials Password Change
Request
POSTcredentials10user_id
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Response
statusCode000 statusMessagesuccess
Change Own Credentials Password Change
Request
POSTcredentials10me
type Password fields [ fieldNamecurrentPassword fieldValueOldSecretPassword fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Credential Management Get CredentialThis section defines the APIs available for Get Credentials
The API neither displays the actual KBA nor the password but it only serves as a mechanism to display what is setNote
Credential Management API Get Credentials
Usage Resource Method
List type of credentials set for a user credentialsltltversiongtgtuser_id GET
Sample Password Reset Call
List Type of Credentials Set for a User Password Only
The following output is displayed only if the password is set The actual password is never displayed
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
[ type Password fields [ fieldNamenewPassword fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User Password and KBA
The following output is displayed only if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Password fields [ fieldNamecurrentPassword fieldValuexxxxxxxxxx ] type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
List Type of Credentials Set for a User KBA Only
The following output is displayed if the password and KBA are set
Request
GETcredentials10user_id
Response
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
[ type Challenge QampA fields [ fieldName01 fieldValuexxxxxxxxxx fieldName03 fieldValuexxxxxxxxxx ]]
Credential Management KBAThis section defines the APIs available for KBA Password Reset
Credential Management API KBA
Usage Resource Method
Change Credentials credentialsltltversiongtgtuser_id POST
Change Own Credentials credentialsltltversiongtgtme POST
SetUpdate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id PATCH
Validate ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id POST
Delete ones own challenge question answers credentialsltltversiongtgtchallengeqauser_id DELETE
Get challenge questions credentialsltltversiongtgtchallengeqalang GET
Data Format for KBA Store in Directory
Each KBA answer is stored in the following format in the directory attribute
AuthStore_KBA_Schemajson
Sample KBA Calls
Change Credentials KBA
Request
POSTcredentials10user_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Change Own Credentials KBA
Request
POSTcredentials10me
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
SetUpdate Ones Own Challenge Question Answers
Request
PATCHcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Validate Ones Own Challenge Question Answers
Request
POSTcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldValueMy Answer to 01 fieldName02 fieldValueMy Answer to 02 ]
Response
statusCode000 statusMessagesuccess
Delete Ones Own Challenge Question Answers
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Request
DELETEcredentialsltltversiongtgtchallengeqauser_id
type Challenge QampA fields [ fieldName01 fieldName02 ]
Response
statusCode000 statusMessagesuccess
Get Challenge Questions
Request
GETcredentialsltltversiongtgtchallengeqalang
Response
statusCode 000 statusMessage success credentials type Challenge QampA fields [ fieldName01 fieldValueWhat is your mothers maiden name fieldName02 fieldValueWhere is your city of birth fieldName03 fieldValueWhats your favorite food ]
Credential Management OTPThis section defines the APIs available for OTP
Credential Management API OTP
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
Usage Resource Method
Obtain ones own OTP Code credentialsltltversiongtgtotpuser_id GET
Sample OTP Calls
Change Credentials OTP
Request
POSTcredentials10user_id
type OTP fields [ fieldNameOTP_CODE fieldValue123456 fieldNamenewPassword fieldValueSecretPassword ]
Response
statusCode000 statusMessagesuccess
Obtain Ones Own OTP Code
Request
GETcredentials10otpuser_id
Response
statusCode 000 statusMessage success credentials type OTP fields [ fieldName OTP_CODE fieldValue 793458 ]
Validate Ones Own OTP Code
Request
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
POSTcredentials10otpuser_id
type OTP fields [ fieldNameOTP_Code fieldValue123456 ]
Response
statusCode000 statusMessagesuccess
JSON SchemaThe following schemas are used for request and response payload
User Profile UserProfilejsonCredential CredentialsjsonSearch Query SearchQueryjson
Note that these schemas are for single object payload only When there is a need to use a multi-valued object an array of the above mentionedschemas are used
Go to to look at the sample JSON payloadSample JSON Payload
JSON Schema and Authentication Store Attribute Mapping
JSON Group Authentication Store JSON Attribute Name
uid uid uid
name givenName givenName
cn displayName
sn familyName
emails primaryEmail emailsprimary = true
mail emails
phoneNumbers telephoneNumber Work
mobile Mobile
homePhone Home
addresses postalAddress zip city country addressestype = Home
socialConnections externalUID idp identifier
systemAttributes regComplete regComplete
emailVerified emailVerified
nonVerifiedEmail nonVerifiedEmail
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
source source
extendedAttributes aListCardNumber aListCardNumber
aListHomeStore aListHomeStore
JSON Schema and Preference Store Attribute Mapping
JSON Group Preference Store Attributes JSON Schema Attribute
addresses billingAddress addressestype=Billing
shippingAddress addressestype=Shipping
extendedAttributes preferredStoreLocation preferredStoreLocation
preferredFood preferredFood
preferredBeverage preferredBeverage
favoriteRestaurant favoriteRestaurant
mobileAppPush mobileAppPush
userPreferences userPreferences
termsOfUse termsOfUse
profileURL profileURL
photoURL photoURL
maritalStatus maritalStatus
incomeRange incomeRange
ageRange ageRange
cfaAgeRangeEffectiveDate cfaAgeRangeEffectiveDate
birthDate dateOfBirth
emailOptIn emailOptIn
smsOptIn smsOptIn
Sample JSON PayloadsThe following are the sample JSON payloads
SampleAddUpdateUserjsonSampleSearchQueryjson
- Integration Guide
- Granting temporary access to public server for SCP
- OAuth 20 Clients
- OAuth 20 Integration
- OAuth 20 Integration Endpoints Sample Requests and Sample Responses
- PingFederate SAML Vs OpenToken
- PingFederate and CloudHSM Integration
- PingFederate OAuth Vs OpenAM OAuth
- PingFederate TimeOut Values
- SocialIDM User Instructions
- User Profile Integration
- API
- User Profile Management APIs
- Add User Profile
- Get User Profile
- Update User Profile
- Search Users
- Deactivate an account
- LinkUnlink Account
- Credential Management APIs
- Credential Management Admin Password Reset
- Credential Management Change Password
- Credential Management Get Credential
- Credential Management KBA
- Credential Management OTP
- JSON Schema
- Sample JSON Payloads
top related