Activating and using the IDTA parameter in RACROUTE REQUEST=VERIFY
- Linking Multiple Authentication API Calls
- Replaying Proof of Authentication
Linking Multiple Authentication API Calls
In some cases, an application which performs user authentication may be required to call the RACROUTE authentication APIs multiple times to complete the authentication process. Applications can use an IDT to allow RACROUTE to link authentication status information between these multiple authentication API calls.
An example of an authentication scenario which requires multiple API calls is when a “password expired” event occurs. An application may initially attempt to authenticate a user by prompting a user for a password and subsequently call RACROUTE REQUEST=VERIFY. This RACROUTE call may fail with a return code which indicates that the password is expired. The application must then prompt the user for a new password and re-call RACROUTE REQUEST=VERIFY again for the same user with an updated parameter list. The IDTA parameter allows these multiple API calls to be linked together for more intelligent authentication processing. This is especially important when users are authenticated with one time use Multi-Factor Authentication (MFA) credentials.
Replaying Proof of Authentication
Some applications have a need to authenticate a user, and then replay that authentication multiple times. These applications may cache the user provided credential and replay it back to RACROUTE. This authentication pattern does not work well for users provisioned with single use MFA token codes instead of passwords. The Identity Token support allows applications to authenticate a user and receive proof of that authentication. The returned IDT can be specified on subsequent calls to RACROUTE instead of other authentication credentials like a password. A signed IDT can be returned to an end user for later use by an application.
Identity Token Formats
The Identity Token Area (IDTA) is a flexible interface designed to support different types of Identity Tokens (IDT) going forward. Currently RACROUTE has support for an IDT in the format of a JSON Web Token (JWT). In the future RACROUTE may support other IDT formats.
RACROUTE JWT Claims
The IDT contains information regarding the end user including how the user was authenticated. When the IDT is in the format of a JSON Web Token (JWT) this information is encoded in a set of JWT claims. Some of the claim values that RACROUTE encodes in the JWT can be controlled by the IDTDATA class profile.
- The "iss" (Issuer) Claim:
- The “iss” claim is used to identify the issuer of the JWT.
- For JWT generation, the “iss” value is set to “saf”.
- For JWT validation, the “iss” value must be set to “saf”.
- The "sub" (Subject) Claim:
- The “sub” claim is used to identify the subject user ID for the JWT.
- For JWT generation, the “sub” value is set to the USERID parameter.
- For JWT validation, the “sub” value must match the specified USERID parameter.
- The "aud" (Audience) Claim:
- The “aud” claim is used to identify which application names can use this JWT. When a JWT “aud” claim contains the “*ANYAPPL*” string it can be used by any application.
- For JWT generation, the “aud” value includes the specified APPL application name parameter or the default application name if one was not specified. An IDTDATA class profile can be created to configure if the “*ANYAPPL*” string is also included in “aud” value. By default, the “*ANYAPPL*” string is included in the “aud” value.
- For JWT validation, the “aud” must contain a value that matches the APPL parameter or the “aud” must contain a value that matches the default application name when an APPL parameter is not specified or the “aud” must contain the “*ANYAPPL*” string.
- The "exp" (Expiration Time) Claim:
- The “exp” claim is used to indicate JWT expiration time.
- For JWT generation, an IDTDATA class profile can be created to configure the JWT timeout value. By default, the “exp” value is set using a timeout value of 5 minutes.
- For JWT validation, the “exp” value must not be older than the current time.
- The "iat" (Issued At) Claim:
- The “iat” claim is used to indicate the time the JWT was issued.
- For JWT generation, the “iat” value is set to the current time.
- The 'jti" (JWT ID) Claim:
- The “jti” claim is used to encode a unique identifier for the JWT.
- For JWT validation, the "iat" value must be a number.
- For JWT generation, the “jti” value is set to a unique value.
- For JWT validation, the “jti” value must be at least 8 characters long and no more than 64 characters long.
- The "txn" (Transaction Identifier) Claim:
- The “txn” claim is used to encode a unique identifier which can be shared between a set of related JWTs.
- For JWT generation, when an input JWT was not specified the “txn” value is set to a unique value. When an input JWT was specified the output “txn” value is set to same “txn” value as the input JWT.
- For JWT validation, “txn” value must be at least 8 characters long and no more than 64 characters long.
- The "amr" (Authentication Method References) Claim:
- The “amr” claim is used to indicate which methods were used to authenticate the subject.
- For JWT generation, the “amr” values are set based on which methods were used to authenticate the user.
- For JWT validation, the “amr” values are used as part of the authentication process.
- More details on the “amr” claim are provided in the topic for the AMR Claim.
RACROUTE use of the AMR Claim
The “amr” claim is used by RACROUTE to indicate which methods were used to authenticate the subject. The RACROUTE authentication methods are divided into MFA methods and SAF methods. In some cases, there may be both MFA and SAF authentication methods for a single user.
For JWT generation, the “amr” are created values based on the methods that were used to authenticate the user.
For JWT validation, the “amr” values are used as part of the authentication process. RACROUTE will validate that the “amr” values are a valid combination of the supported values as listed below.
- “saf-pwd” – The user was authenticated with a password.
- "saf-phr" - The user was authenticated with a password phrase.
- "saf-ptkt" - The user was authenticated with a PassTicket.
- "mfa-only" - The user was authenticated with MFA.
- "mfa-ptkt" - An MFA provisioned user was authenticated with a PassTicket.
- "mfa-comp" - The user was authenticated with MFA. A SAF authentication method name ("saf-pwd" or 'saf-phr") is required.
- "mfa-pwfb" - An MFA provisioned user was not authenticated with MFA. A SAF authentication method name is required.
- "mfa-bypass" - An MFA provisioned user was not authenticated with MFA for this application. A SAF authentication method name is also required. A JWT with this claim can only be used on an application which is configured to be bypassed.
- "mfa-exp" - The user was authenticated with MFA, but the knowledge factor portion of the credential was expired. The user must set a new knowledge factor before they can successfully logon.
- "mfa-newinf" - The user was authenticated with MFA, but the user attempted to set a new knowledge factor which was not valid. The user must set a new knowledge factor before they can successfully logon.
- "mfa-nmi" - MFA processing requires more information to complete authentication.
In some cases, a JWT may be returned when the user is not yet fully authenticated. The following MFA “amr” claims indicate that the user is still in the process of being authenticated: “mfa-exp”, “mfa-newinv” and “mfa-nmi”. A JWT with these claims may be specified back to RACROUTE along with any other required parameters to complete the authentication process. RACROUTE may then generate a new output JWT with updated “amr” claims.
Signed and Unsigned Identity Tokens
RACROUTE can create a signed or unsigned IDT. The security administrator may configure profiles in the IDTDATA class to control how RACROUTE creates the IDT including which ICSF key is used to generate and validate the IDT signature. An installation can create the key in ICSF by calling the PKCS#11 Generate Secret Key (CSFPGSK) or Token Record Create (CSFPTRC) callable services.
Applications may return a signed IDT to an end user. An unsigned IDT should not be returned to an end user because RACROUTE will not accept an unsigned IDT from an end user. When an application will return an IDT or accept an IDT from and end user, it must turn on the IDTA_End_User_IDT flag. When the IDTA_End_User_IDT is on, RACROUTE will not return an unsigned IDT or accept a specified unsigned IDT. An authorized application which keeps an unsigned IDT under its own control may generate and specify an unsigned IDT to RACROUTE.
When a signed IDT is specified, and signature validation fails RACROUTE returns the 8/8/0 return codes and the specified user’s revoke count is incremented.
When a signed IDT is specified, and there is no associated IDTDATA class profile with a signature key configured, RACROUTE indicates that signature validation cannot be performed by returning the 8/6C/15 return codes.
RACROUTE supports generating and validating JWTs with the ‘HS256’ HMAC256, ‘HS384’ HMAC384 or ‘HS512’ HMAC512 signature algorithms. RACROUTE does not support encrypted JWTs.
Protecting an IDT
When an application receives an Identity Token (IDT) from RACROUTE, it must keep it in a protected location. An IDT can be used to authenticate a user though RACROUTE and therefore must be kept in protected storage. Also note that some applications may allow IDTs to be specified from an end user.
Identity Token Expiration
An IDT has a defined expire date, after which it is no longer considered valid. When an expired IDT is supplied to RACROUTE REQUEST=VERIFY the request will fail with the 8/6Cx/E return codes. The calling application should discard the expired IDT, and re-prompt the user for authentication credentials before calling RACROUTE again.
When RACROUTE creates an IDT the default timeout value is 5 minutes after creation. The security administrator can create an IDTDATA class profile to configure a different timeout value.
Expired Password or Password Phrase
An IDT includes information regarding how the user originally authenticated. When the user is being authenticated with an IDT which indicates the original authentication was a password or password phrase and that authenticator is expired on the system, RACROUTE will fail the request with the 8/C/0 “password or password phrase expired” return codes. In this case the user must provide a new password or password phrase before the RACROUTE will complete with a successful return code. The application should prompt the user to enter their new password or new password phrase value before calling RACROUTE again.
Changing the password or password phrase with a specified Identity Token
A valid specified IDT can be used instead of the current password or password phrase when specifying a new password or new password phrase. The normal password change rules apply. When the IDT indicates that the user has authenticated with a password a new password may be specified. When the IDT indicates the user has authenticated with a password phrase a new password phrase may be specified. When the IDT indicates the user has authenticated with a PassTicket a new password or new password phrase may be specified.
IDT Configuration
The security administrator can configure an IDTDATA class profile to control how certain fields in an IDT are generated and how a specified IDT is validated. The IDTDATA class profile name is based on the IDT type, application name, user ID and IDT issuer. Generic characters are allowed in the profile name.
<IDT Type>.<application name>.<user ID>.<IDT issuer name>RDEFINE IDTDATA JWT.APPL01.USER01.SAF IDTPARMS(SIGTOKEN(mytoken)
SIGSEQNUM(1) SIGCAT(T) SIGALG(HS256) ANYAPPL IDTTIMEOUT(30))- RALTER (Alter general resource profile) in z/OS Security Server RACF Command Language Reference
- RDEFINE (Define general resource profile) in z/OS Security Server RACF Command Language Reference
- RLIST (List general resource profile) in z/OS Security Server RACF Command Language Reference.
When the IDTDATA class is not active, RACROUTE will ignore the IDTA parameter. The IDTDATA class must be active and RACLISTed before RACROUTE will use any profiles for the generation or validation of an IDT.
When there is no covering IDTDATA class profile, RACROUTE will generate an IDT with the default values. An IDT created with the default values will be unsigned, be accepted by any application name and will have a timeout value of 5 minutes.
IDTA Parameter Format
| Name | Len | Input/Output | Description |
|---|---|---|---|
| IDTA_ID | 4 | Input | Eyecatcher: IDTA |
| IDTA_Version | 2 | Input | Version: 1 |
| IDTA_Length | 2 | Input | Length: 36 - Total length of the IDTA. |
| IDTA_IDT_Buffer_Ptr | 4 | Input | Identity Token Pointer: Points to a caller allocated buffer for the Identity Token. |
| IDTA_IDT_Buffer_Len | 4 | Input | Identity Token Buffer Length: Length of the Identity Token buffer. The current minimum
size is 1024. In a future update the minimum size may be increased. When the input buffer length is smaller than the minimum or insufficient to hold the output IDT, RACROUTE will return the return codes 8/70/1 and the required size will be set in the IDTA_IDT_Len Identity Token Length field. |
| IDTA_IDT_Len | 4 | Input / Output | Identity Token Length: Length of the Identity Token. Caller should set to zero if
there is no supplied Identity Token. When RACROUTE generates an IDT, the IDT length will be set on output. A new output IDT may be written over an existing input IDT. When the input IDTA_IDT_Buffer_Len Token Buffer Len field is not sufficient size to hold the output token, RACROUTE will set the IDTA_IDT_Len to the required size and fail with the return codes 8/70/1. The caller must reallocate the buffer with the larger size and reset to the IDTA_IDT_Len to zero or the length of an supplied IDT. When there is an error processing a specified IDT RACROUTE will set the IDTA_IDT_Len to zero. |
| IDTA_IDT_Type | 2 | Input | Identity Token Type:
|
| IDTA_IDT_Gen_RC | 2 | Output | Idenitity Token Generation Return Code:
|
| IDTA_IDT_Prop_Out | 2 | Output | Identity Token Output Properties bits
|
| IDTA_IDT_Prop_In | 2 | Input | Identity Token Input Properties bits:
|
| * | 8 | N/A | Reserved |
Initial RACROUT REQUEST=VERIFY Call with an IDTA
- Header Fields:
- Set the IDTA_ID to “IDTA”.
- Set the IDTA_VERSION to 1.
- Set the IDTA_LENGTH to 36.
- IDT Buffer Parameter Fields:
- Set IDTA_IDT_Type to 1.
- Set IDTA_IDT_Buffer_Ptr to point to a caller-allocated buffer for returning an IDT.
- Set the IDTA_IDT_Buffer_Len to the length of the allocated IDT buffer. The minimum IDT buffer length is 1024.
- When an IDT is not specified, set IDTA_IDT_Len to 0.
When an IDT is specified, copy the supplied IDT into the IDT buffer and set the IDTA_IDT_Len to the length of the supplied IDT.
- When the IDT is provided by an end user or the IDT is going to be returned to an end user, set the IDTA_End_User_IDT flag on. When IDTA_End_User_IDT is off, an unsigned IDT will be accepted by RACROUTE and may be returned by RACROUTE.
- Other Fields: Initialize all other fields to binary zero.
Subsequent RACROUTE REQUEST=VERIFY Calls with an IDTA
On subsequent calls to RACROUTE REQUEST=VERIFY for the same user, within the same set of authentication API calls, the IDTA parameter should be passed back in as it was returned from the previous RACROUTE call. Depending on the authentication scenario RACROUTE may overwrite a supplied IDT with a new IDT within the IDT buffer.
When an application switches to authenticate a different user ID, the IDTA should be reinitialized as new. When the IDTA is not reinitialized, the RACROUTE call will fail when the IDTA token user ID does not match the supplied RACROUTE user ID.
IDTA Error Handling
Applications which specify the IDTA keyword must be prepared to handle certain error scenarios.
When there is an error processing a specified IDT RACROUTE will return one of the 8/6C/x return code combinations. In this case, the IDTA_IDT_Len field to also set to zero.
In some cases, an IDT may not be generated when an application has requested one. When an IDT is successfully generated, the IDTA_SAF_IDT_Return field will be set ON. When an IDT is not generated the IDTA_SAF_IDT_Return field will be set OFF. When there was an error encountered attempting to generate the IDT, the IDTA_IDT_Gen_RC field will be set to indicate the error reason.
When the IDTA keyword is specified and the IDTDATA class is active RACROUTE may return the 8/74/1 return code combination in some cases while authenticating MFA provisioned users. In this case, the application should prompt the user for current credentials again and call RACROUTE with the returned IDT.
Other RACROUTE REQUEST=VERIFY Parameters
When a specified IDTA contains a supplied IDT, RACROUTE attempts to use the IDT for authentication. When the supplied IDT contains a SAF AMR claim the PASSWORD and PHRASE parameters are ignored by SAF.
When an IDT is supplied and the USERID parameter is omitted, the subject name from the IDT will be used as the user ID.
The new password or new password phrase parameters may be specified with a specified IDT. The normal new password or new password phrase rules apply.
The IDTA keyword is only processed when RELEASE is set to PLV0001 or higher and when the ENV keyword is set to CREATE.
The IDTA keyword is not valid when the ICRX or IDID keywords are specified.
The IDTA keyword is ignored when PASSCHK=NO or ENVIRIN is specified.
