### Implement OAuth 2.0 Token Exchange Rule (JavaScript)

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

This JavaScript code snippet demonstrates the implementation of the OAuth 2.0 Token Exchange mapping rule. It imports the necessary rule and provides comments explaining its functionality, including storing actor claims and supporting token-to-token exchange. It also includes an example of a token exchange request.

```javascript
importMappingRule("Oauth_20_TokenExchange");

// Token exchange handles delegation flows
// Stores "act" (actor) claims in OAuth token extra attributes
// Supports token-to-token exchange for service-to-service delegation

// Example token exchange request:
// POST /token
// grant_type=urn:ietf:params:oauth:grant-type:token-exchange
// subject_token=<access_token>
// subject_token_type=urn:ietf:params:oauth:token-type:access_token
// requested_token_type=urn:ietf:params:oauth:token-type:access_token

// Rule automatically processes subject_token and creates new token
// with original user identity preserved in "act" claim chain

```

--------------------------------

### OAuth 2.0 Post-Token Mapping for Attribute Association and Introspection

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

This post-token mapping rule handles operations after OAuth 2.0 token creation. It supports associating custom attributes with client credentials grants, retrieving these attributes, and can be extended for token deletion, HTTP callouts, MFA authenticator registration, and introspection enforcement. The example demonstrates associating and retrieving custom attributes.

```javascript
// Example: Associate custom attributes with client credentials grant
var cc_demo = true;
if (request_type == "access_token" && grant_type == "client_credentials") {
    // Associate extra attribute to authorization grant
    OAuthMappingExtUtils.associate(state_id, "special_id", "sp_" + state_id);
    OAuthMappingExtUtils.associate(state_id, "friendly_name", "phone client");

    // Retrieve associated attributes
    var attrKeys = OAuthMappingExtUtils.getAssociationKeys(state_id);
    for (var i = 0; i < attrKeys.length; i++) {
        var value = OAuthMappingExtUtils.getAssociation(state_id, attrKeys[i]);
        stsuu.addContextAttribute(new Attribute(attrKeys[i], "urn:ibm:jwt", value));
    }
}

```

--------------------------------

### Branching Helper Functions for Authentication Decisions

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

This Javascript code provides utility functions for branching authentication decisions. It includes functions to retrieve branch definitions, map authentication mechanisms to branches, and fetch user enrollment data for various methods like password, FIDO2, and MMFA. It relies on macros for branch definitions and assumes the availability of username.

```javascript
// Get branches defined in policy
function getBranches() {
    return JSON.parse(macros.get("@BRANCHES@"));
}

// Build mechanism-to-branch mapping
var result = getMechanismsAndBranchMap();
var mechanisms = result[0];
var branchMap = result[1];
// mechanisms: ["urn:ibm:security:authentication:asf:password", "urn:ibm:security:authentication:asf:fido2"]
// branchMap: {"urn:ibm:security:authentication:asf:password": "Password Branch"}

// Get user's enrolled methods
var userData = getUserData(username, mechanisms);
var enrolledMethods = userData[0];
// enrolledMethods: [{"id": "abc123", "type": "password", "enabled": true}]

// Get FIDO registrations
var fidoRegs = getFIDORegistrations(username);
// fidoRegs: [{"credentialId": "xyz789", "aaguid": "...", "userVerified": true}]

// Get MMFA registrations
var mmfaRegs = getMMFARegistrations(username);
// mmfaRegs: [{"id": "mmfa456", "fingerprintEnrolled": true}]

```

--------------------------------

### Implement Identifier-First Authentication Flow

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

Implements an identifier-first authentication flow supporting multiple methods like password, FIDO2, and MMFA. The user first provides their username, and then selects their preferred authentication method. This logic determines the subsequent authentication step based on user choice and enabled methods.

```javascript
// Enable authentication methods
var mmfaEnabled = true;
var fidoEnabled = true;
var fido2PAIREnabled = true;
var redirectEnabled = true;

// User submits username
var username = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "username");

// User chooses authentication method
var action = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "action");
if (action == "chooseAuth") {
    var type = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "type");

    if (type == "fido" && fidoEnabled) {
        state.put("decision", "FIDO Authentication");
        result = true;
    } else if (type == "mmfa" && mmfaEnabled) {
        state.put("decision", "MMFA Authentication");
        result = true;
    } else if (type == "password") {
        state.put("decision", "Username Password");
        result = true;
    }
}
```

--------------------------------

### OAuth 2.0 Pre-Token Mapping for Validation and Limiting

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

This pre-token mapping rule executes before OAuth 2.0 access token generation. It supports ROPC username/password validation against a registry or external service, limits token grants per user/client, and allows for ID token customization based on OIDC scopes. It returns an error if validation fails or limits are exceeded.

```javascript
// Configure ROPC validation with registry or external service
var ropc_registry_validation = true;  // Enable username/password validation
var ropc_http_demo = false;
var verificationServer = "https://your-host.com/userVerifier.jsp";

// Limit tokens per user per client (default: 20 tokens)
var limit_oauth_grants_per_user_per_client = true;
var max_oauth_grants_per_user_per_client = 20;
var limit_method = "strict";  // "strict" or "lru" 

// The rule validates credentials before token creation
// preventing invalid user tokens from being cached
// Returns error if validation fails or limit exceeded

```

--------------------------------

### Integrate IBM Cloud Identity for Strong Authentication

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

This Javascript code integrates with IBM Cloud Identity for strong authentication, supporting various methods like SMS OTP, Email OTP, TOTP, and IBM Verify push notifications. It allows for just-in-time enrollment and handles authentication method selection and transaction status polling. It requires configuration of enabled methods and can use a custom transaction message.

```javascript
importPackage(Packages.com.ibm.security.access.ciclient);

// Configure enabled authentication methods
var enabledMethods = ["Verify", "SMSOTP", "EmailOTP", "TOTP", "TransientEmail", "TransientSMS"];
var verifyTransactionMessage = "You have a pending authentication challenge.";
var jitEnrollment = true;  // Enable just-in-time enrollment

// Handle authentication method selection
var action = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "action");

if (action == "chooseMethod") {
    var methodType = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "methodType");

    if (methodType == "SMSOTP") {
        // Create SMS OTP verification
        var verification = CIClient.createVerification(username, "smsotp", otpCorrelation);
        state.put("verificationId", verification.id);
        state.put("transactionId", verification.transactionId);
    } else if (methodType == "Verify") {
        // Create IBM Verify transaction
        var transaction = CIClient.createTransaction(username, verifyTransactionMessage);
        state.put("transactionId", transaction.id);
    }
}

// Poll transaction status
if (action == "poll") {
    var txnId = state.get("transactionId");
    var transaction = CIClient.getTransaction(txnId);
    if (transaction.state == "VERIFY_SUCCESS") {
        success.setValue(true);
    }
}

```

--------------------------------

### Collect and Validate User Email for Lost ID Recovery

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

This Javascript code collects and validates a user's email address for a lost ID recovery flow. It integrates with SCIM for user lookup and reCAPTCHA for validation. It expects 'emailAddress', 'surname', and 'g-recaptcha-response' as request parameters and outputs the 'username' to the session if successful. It requires SCIM and reCAPTCHA client configurations.

```javascript
importClass(Packages.com.ibm.security.access.scimclient.ScimClient);
importClass(Packages.com.ibm.security.access.recaptcha.RecaptchaClient);

// Collect email and surname from user
var email = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "emailAddress");
var surname = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "surname");

// Validate reCAPTCHA
var captchaResponse = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "g-recaptcha-response");
var captchaVerified = RecaptchaClient.verify(captchaResponse, macros.get("@RECAPTCHASECRETKEY@"), null);

if (captchaVerified) {
    // Look up user via SCIM
    var scimConfig = context.get(Scope.SESSION, "urn:ibm:security:asf:policy", "scimConfig");
    var resp = ScimClient.httpGet(scimConfig,
        "/Users?filter=emails.value%20eq%20" + encodeURIComponent(email)));

    var respJson = JSON.parse(resp.getBody());
    if (respJson.totalResults == 1) {
        // Verify surname matches
        if (respJson.Resources[0].name.familyName.toLowerCase() == surname.toLowerCase()) {
            context.set(Scope.SESSION, "urn:ibm:security:asf:response:token:attributes",
                       "username", respJson.Resources[0].userName);
        }
    }
}

```

--------------------------------

### Mediate FIDO2 Registration and Authentication

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

Mediates FIDO2 registration and authentication flows by controlling various security options. It allows configuration of attestation options, assertion requirements, user verification, and resident key enforcement. This rule helps in securely managing FIDO2 device interactions.

```javascript
// Configure FIDO2 mediation options
var is_limit_registrations = true;  // Limit to 5 registered devices
var save_example_attribute = true;  // Save custom attributes
var return_needs_register_error = true;
var assert_uv_when_registered = true;  // Require UV if registered with UV
var enforce_rk_and_uv = true;  // Enforce resident key and user verification

// Associate custom attribute during registration
function associate_attribute(attribute_name, attribute_value) {
    if (context.requestType == "attestation_result") {
        attributes.put(attribute_name, attribute_value);
    }
}

// Retrieve attribute during authentication
function get_attribute(attribute_name) {
    return context.requestData.registration.attributes[attribute_name];
}

// Automatically mediates FIDO2 WebAuthn API calls
// Modifies attestation options and validates assertion results

```

--------------------------------

### Customize SAML 2.0 Identity Provider Assertions

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

Customizes SAML 2.0 assertions issued by an Identity Provider. This mapping rule allows control over the NameID, AuthnContext, attributes, and attribute statements within the SAML assertion. It provides flexibility in tailoring SAML responses for various integration needs.

```javascript
importClass(Packages.com.tivoli.am.fim.trustserver.sts.uuser.Attribute);
importClass(Packages.com.tivoli.am.fim.trustserver.sts.uuser.AttributeStatement);

// Set NameID in SAML assertion
stsuu.addPrincipalAttribute(
    new Attribute("name",
                  "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
                  "john.doe@example.com")
);

// Set AuthnContextClassRef
stsuu.addAttribute(
    new Attribute("AuthnContextClassRef",
                  "urn:oasis:names:tc:SAML:2.0:assertion",
                  "urn:oasis:names:tc:SAML:2.0:ac:classes:Password")
);

// Add attributes to SAML assertion
stsuu.addAttribute(new Attribute("first_name", "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "john"));
stsuu.addAttribute(new Attribute("last_name", "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "doe"));

// Add additional attribute statement
var attributeStatement = new AttributeStatement();
attributeStatement.addAttribute(
    new Attribute("email_address", "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "john.doe@example.com")
);
stsuu.addAttributeStatement(attributeStatement);

```

--------------------------------

### OIDC ID Token Mapping for Claims and Scopes

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

This mapping rule controls which user attributes are included as claims in the OIDC ID token, based on approved scopes. It defines mappings between ID token claims and credential attributes, as well as mappings between scopes and the attributes they permit. The rule automatically processes approved scopes to populate the ID token.

```javascript
// Define attribute mappings
var idTokenAttrsToCredAttrs = {
    "email": "emailAddress",
    "given_name": "firstName",
    "family_name": "lastName"
};

// Define scope-to-attribute mappings
var scopeToIDTokenAttrs = {
    "profile": ["given_name", "family_name"],
    "email": ["email"]
};

// Rule automatically processes approved scopes and includes
// corresponding attributes in ID token
// If user approved "profile" and "email" scopes,
// ID token will contain: given_name, family_name, email

```

--------------------------------

### FAPI JWT Request Object Validation

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

This rule validates JWT request objects for Financial-grade API (FAPI) compliance. It enforces the presence of required claims (exp, nbf, scope, nonce, redirect_uri), checks signature algorithms (disallowing 'none' or 'RS256'), and ensures expiration constraints (within 60 minutes). Validation failures result in a 400 error with 'invalid_request'.

```javascript
// Validates FAPI-compliant request objects
// Checks required claims: exp, nbf, scope, nonce, redirect_uri
// Enforces constraints:
// - exp must be within 60 minutes
// - nbf must be within 60 minutes
// - alg cannot be "none" or "RS256"

// Example validation failure:
// OAuthMappingExtUtils.throwSTSCustomUserPageException(
//     "exp is greater than 60 mins.", 400, "invalid_request"
// );

// Automatically invoked during OAuth authorization
// Returns 400 error with invalid_request if validation fails

```

--------------------------------

### Validate FAPI JWT Client Authentication

Source: https://context7.com/ibm-security/verify-access-aac-mapping-rules/llms.txt

Validates JWT-based client authentication for FAPI flows. It checks the JWT's signature, expiration, issuer, and audience, enforcing FAPI requirements. This rule ensures that client credentials presented as JWT assertions meet security standards.

```javascript
importClass(Packages.com.tivoli.am.fim.trustserver.sts.utilities.OAuthMappingExtUtils);

// Validates client_assertion JWT parameter
// Checks JWT signature, expiration, issuer, audience
// Enforces FAPI requirements for client authentication
var defID = OAuthMappingExtUtils.getClient(claims.iss).getDefinitionID();
var isFapi = OAuthMappingExtUtils.getDefinitionByID(defID).getOidc().getFapiCompliant();

if (isFapi) {
    // Validate JWT claims and signature
    // Throw exception if validation fails
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.