Initialization
If Kerberos authentication was not successful, then the way to proceed is to issue the following request:
GET /idp/ws/rest/authn HTTP/1.1 Accept: application/json
The response from the server will always be of type username, username+password or policyChoice and will contain other pieces of information needed to construct the initial authentication page:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "username+password",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"availableRealms": [
{
"id": "internal",
"name": "Internal"
},
{
"id": "11541860-161f-11e6-aec5-005056c00008",
"name": "Realm 1"
},
{
"id": "233d3570-161f-11e6-aec5-005056c00008",
"name": "Realm 2"
}
],
"allowQRCodeScan": false,
"allowKerberos": false,
"claimAccountLink": {
"href": "/arms/claim/",
"displayName": "Claim My Account"
},
"helpLinks": [
{
"href": "/arms/forgotmyusername",
"displayName": "Forgot My Username"
},
{
"href": "/arms/forgotmypassword?redirect_to=/arms",
"displayName": "Forgot My Password"
}
]
}Let's ignore the type for now, it will be discussed later.
The id property is a value that must be included in the subsequent request
The availableRealms property is an array of authentication realms to which the user may authenticate. This is only included if RapidFederation is currently configured for realms other than the default which has the id value of internal.
The allowQRCodeScan property is a boolean indicating that the user may initiate the authentication process by scanning a QR code
The allowKerberos property is a boolean indicating that the user may initiate the authentication process by attempting Manual Kerberos Authentication.
The claimAccountLink object contains the link location (href) as well as the text to display on the button (displayName) which allows a user to claim their account. This object will only be included in the response if the link should be displayed.
The helpLinks property is an array of objects describing help links and their display names which should be available to the user when they click the "Need help?" button on the login page. If no help links are configured, this property will not be included.
Username/Password
This initial authentication step is required if the type property in the initial response has the value username+password. It indicates that
There are no enabled Authentication Policies defined for RapidFederation OR
All enabled Authentication Policies require Password as the initial authentication method
A valid username and password combination is required to proceed to the next authentication step:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "username+password",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"username": "someuser",
"password": "mysecurepassword"
}Additionally, if authenticating against a realm other than internal is desired, the realm property may be included in the request body:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "username+password",
"realm": "233d3570-161f-11e6-aec5-005056c00008",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"username": "someuser",
"password": "mysecurepassword"
}Here is an example of a response from the server if the username/password combination sent in the request is incorrect:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "username+password",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"availableRealms": [
{
"id": "internal",
"name": "Internal"
},
{
"id": "11541860-161f-11e6-aec5-005056c00008",
"name": "Realm 1"
},
{
"id": "233d3570-161f-11e6-aec5-005056c00008",
"name": "Realm 2"
}
],
"claimAccountLink": {
"href": "/arms/claim/",
"displayName": "Claim My Account"
},
"helpLinks": [
{
"href": "/arms/forgotmyusername",
"displayName": "Forgot My Username"
},
{
"href": "/arms/forgotmypassword?redirect_to=/arms",
"displayName": "Forgot My Password"
}
],
"error": {
"type": "simple",
"message": "Incorrect Username and/or Password"
}
}Notice the error property in the response. It has a type value of simple which means that the associated message should be displayed to the user.
Here is an example of the response from the server if the username & password combination were correct but the user is required to update their password before continuing:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "username+password",
"id": "cd4f0ab0-2dc7-11e6-937b-005056c00008",
"availableRealms": [
{
"id": "internal",
"name": "Internal"
},
{
"id": "11541860-161f-11e6-aec5-005056c00008",
"name": "Realm 1"
},
{
"id": "233d3570-161f-11e6-aec5-005056c00008",
"name": "Realm 2"
}
],
"claimAccountLink": {
"href": "/arms/claim/",
"displayName": "Claim My Account"
},
"helpLinks": [
{
"href": "/arms/forgotmyusername",
"displayName": "Forgot My Username"
},
{
"href": "/arms/forgotmypassword?redirect_to=/arms",
"displayName": "Forgot My Password"
}
],
"error": {
"type": "password-expired",
"message": "Your password is expired and must be updated before continuing",
"expiredPasswordText": "CLICK HERE to change your password.",
"targetUrl": "/arms/expired-password",
"username": "8kb+8GQVM2HUGJQtMRxKjNFfUNuboOhcdtBw8VtIlZU=",
"password": "78EV3jkq6IYu/8S2rC4M54NQYwTQRPRaUEaFuNdRx6w="
}
}Notice the error property in the response. It has a type value of password-expired which indicates that the user must change their password and the associated message should be displayed to the user to let them know. The expiredPasswordText, targetUrl, username and password property values are used to construct a link which, when clicked, submits a form in a new window which POSTs the obfuscated username and password to the targetUrl.
Username
This initial authentication step is required if the type property in the initial response has the value username. It indicates that
There is at least one enabled Authentication Policies defined for RapidFederation AND
At least one of the enabled Authentication Policies requires an initial authentication method other than Password.
A valid username is required to proceed to the next step:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "username+password",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"username": "someuser"
}Additionally, if authenticating against a realm other than internal is desired, the realm property may be included in the request body:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "username+password",
"realm": "233d3570-161f-11e6-aec5-005056c00008",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"username": "someuser"
}
If a username which does not successfully map to a valid account is provided in the username request, it will kick off a "Bogus" authentication flow which will always fail.
PolicyChoice
This authentication step allows users to select which authentication policy they want to use to authenticate, and is only present if:
There are multiple authentication policies which are applicable to a user
Authentication Policy Options have been "opted-in" to
Here is an example of the response from the server if either username or username+password has been completed successfully and authentication policy options are enabled:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "policyChoice",
"id": "2f875a60-dbfc-11e6-8449-005056c00008",
"claimAccountLink": {
"href": "/arms/claim/",
"displayName": "Claim My Account"
},
"helpLinks": [
{
"href": "/arms/forgotmyusername",
"displayName": "Forgot My Username"
},
{
"href": "/arms/forgotmypassword?redirect_to=/arms",
"displayName": "Forgot My Password"
}
],
"policies": [
{
"id": "5fda6a30-d1ee-11e6-8629-005056c00008",
"methods": [
{
"type": "password"
}
]
},
{
"id": "4101afb0-d1ee-11e6-8629-005056c00008",
"methods": [
{
"type": "password"
},
{
"type": "rapidPortalChallenge"
}
]
}
]
}Next, the user returns a request with the policy ID that they would like to authenticate with:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"id": "65a22d80-d9c9-11e6-9ed6-005056c00008",
"type": "policyChoice",
"policyId": "5fda6a30-d1ee-11e6-8629-005056c00008"
}