module_oidc.php.dist

<?php

declare(strict_types=1);

/*
 *        |
 *   \  ___  /                           _________
 *  _  /   \  _    GÉANT                 |  * *  | Co-Funded by
 *     | ~ |       Trust & Identity      | *   * | the European
 *      \_/        Incubator             |__*_*__| Union
 *       =
 *
 * This file is part of the simplesamlphp-module-oidc.
 *
 * Copyright (C) 2018 by the Spanish Research and Academic Network.
 *
 * This code was developed by Universidad de Córdoba (UCO https://www.uco.es)
 * for the RedIRIS SIR service (SIR: http://www.rediris.es/sir)
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

use SimpleSAML\Module\oidc\ModuleConfig;
use SimpleSAML\OpenID\Codebooks\ClaimsEnum;
use SimpleSAML\OpenID\Codebooks\CredentialFormatIdentifiersEnum;
use SimpleSAML\OpenID\Codebooks\CredentialTypesEnum;
use SimpleSAML\OpenID\Codebooks\LanguageTagsEnum;

$config = [
    /**
     * (optional) Issuer (OP) identifier which will be used as an issuer (iss)
     * claim in tokens. If not set, it will fall back to the current HTTP
     * scheme, host and port number if no standard port is used.
     * Description of the issuer from OIDC Core specification: "Verifiable
     * Identifier for an Issuer. An Issuer Identifier is a case-sensitive URL
     * using the https scheme that contains scheme, host, and optionally,
     * port number and path components and no query or fragment components."
     */
//    ModuleConfig::OPTION_ISSUER => 'https://op.example.org',

    /**
     * Protocol (Connect) signature algorithm and key-pair definitions,
     * representing supported algorithms for signing, for example, ID Token JWS.
     * The order in which the entries are set is important. The entry set
     * first will have higher priority during signing algorithm negotiation
     * with the client. If the client doesn't designate the desired signing
     * algorithm, the first algorithm in the list will be used for signing (the
     * first entry represents the default algorithm and signing key). Note that
     * the OpenID Connect specification designates `RS256` as the signing
     * algorithm that should be used by default, so you would probably want
     * to use that algorithm as the default (first) one. However, you are free
     * to set other default (first) algorithm as needed.
     * You can also use this config option to advertise any (new) keys, for
     * example, for key-rollover scenarios. Just add those entries later in
     * the list, so they can be published on the OP JWKS discovery endpoint.
     *
     * The format is array of associative arrays, where each array value
     * consists of the following properties (keys):
     * - ModuleConfig::KEY_ALGORITHM - \SimpleSAML\OpenID\Algorithms\SignatureAlgorithmEnum case
     * representing the algorithm.
     * - ModuleConfig::KEY_PRIVATE_KEY_FILENAME - the name of the file
     * containing private key inPEM format, which is available in SSP `cert`
     * folder.
     * - ModuleConfig::KEY_PUBLIC_KEY_FILENAME - the name of the file containing
     * corresponding public key in PEM format, which is available in SSP `cert`
     * folder.
     * - ModuleConfig::KEY_PRIVATE_KEY_PASSWORD - private key password, if
     * needed.
     * - ModuleConfig::KEY_KEY_ID - Optional string representing key identifier.
     * Use if you need to manually set key identifiers to be published. If not
     * set, a public key thumbprint will be generated on the fly and used as a
     * key ID.
     *
     * Note: in v7 of the module, a new way of automatic key ID generation is
     * used. In previous versions, a hash of a public key file was used as a
     * key ID. In v7, a public key thumbprint is used. If you are migrating from
     * a previous version of the module, and you want to keep the old signing
     * key, you should manually set the key ID to the previous value
     * so that clients know that the key did not change.
     */
    ModuleConfig::OPTION_PROTOCOL_SIGNATURE_KEY_PAIRS => [
        [
            ModuleConfig::KEY_ALGORITHM => \SimpleSAML\OpenID\Algorithms\SignatureAlgorithmEnum::RS256,
            ModuleConfig::KEY_PRIVATE_KEY_FILENAME => 'oidc_module_connect_rsa_01.key',
            ModuleConfig::KEY_PUBLIC_KEY_FILENAME => 'oidc_module_connect_rsa_01.pub',
//            ModuleConfig::KEY_PRIVATE_KEY_PASSWORD => 'private-key-password', // Optional
//            ModuleConfig::KEY_KEY_ID => 'rsa-connect-signing-key-2026', // Optional
        ],
        // Example for additionally supported ES256 algorithm with EC keys.
        // Delete it if not needed:
        [
            ModuleConfig::KEY_ALGORITHM => \SimpleSAML\OpenID\Algorithms\SignatureAlgorithmEnum::ES256,
            ModuleConfig::KEY_PRIVATE_KEY_FILENAME => 'oidc_module_connect_ec_p256_01.key',
            ModuleConfig::KEY_PUBLIC_KEY_FILENAME => 'oidc_module_connect_ec_p256_01.pub',
//            ModuleConfig::KEY_PRIVATE_KEY_PASSWORD => 'private-key-password', // Optional
//            ModuleConfig::KEY_KEY_ID => 'ec-connect-signing-key-01', // Optional
        ],
    ],

    /**
     * Authorization code and tokens TTL (validity duration), with given
     * examples. For duration format info, check
     * https://www.php.net/manual/en/dateinterval.construct.php
     */
    ModuleConfig::OPTION_TOKEN_AUTHORIZATION_CODE_TTL => 'PT10M', // 10 minutes
    ModuleConfig::OPTION_TOKEN_REFRESH_TOKEN_TTL => 'P1M', // 1 month
    ModuleConfig::OPTION_TOKEN_ACCESS_TOKEN_TTL => 'PT1H', // 1 hour,

    /**
     * (optional) Timestamp Validation Leeway - additional time tolerance
     * allowed for timestamp validation. This is used when validating
     * timestamps like Expiration Time (exp), Issued At (iat), Not
     * Before (nbf), and similar claims on JWS artifacts.
     * If not set, falls back to 'PT1M' (1 minute).
     *
     * For duration format info, check
     * https://www.php.net/manual/en/dateinterval.construct.php
     */
    ModuleConfig::OPTION_TIMESTAMP_VALIDATION_LEEWAY => 'PT1M',

    /**
     * The default authentication source to be used for authentication if the
     * authentication source is not specified on a particular client.
     */
    ModuleConfig::OPTION_AUTH_SOURCE => 'default-sp',

    /**
     * The attribute name that contains the user identifier returned from IdP.
     * By default, this attribute will be dynamically added to the 'sub'
     * claim in the attribute-to-claim translation table (you will probably want
     * to use this attribute as the 'sub' claim since it designates a unique
     * identifier for the user).
     */
    ModuleConfig::OPTION_AUTH_USER_IDENTIFIER_ATTRIBUTE => 'uid',

    /**
     * The default translate table from SAML attributes to OIDC claims. If you
     * don't want to support a specific default claim, set it to an empty array.
     */
    ModuleConfig::OPTION_AUTH_SAML_TO_OIDC_TRANSLATE_TABLE => [
        /*
         * The basic format is
         *
         * 'claimName' => [
         *     'type' => 'string|int|bool|json',
         *      // For non-JSON types
         *     'attributes' => ['samlAttribute1', 'samlAttribute2']
         *      // For JSON types
         *     'claims => [
         *          'subclaim' => [ 'type' => 'string', 'attributes' => ['saml1']]
         *      ]
         *  ]
         *
         * For convenience the default type is "string" so the type does not
         * need to be defined. If the "attributes" key is not set, then it is
         *  assumed that the rest of the values are SAML attribute names.
         *
         * Note on the 'sub' claim: by default, the list of attributes for 'sub'
         * claim will also contain an attribute defined in the
         * `ModuleConfig::OPTION_AUTH_USER_IDENTIFIER_ATTRIBUTE` setting.
         * You will probably want to use this attribute as the 'sub' claim since
         * it designates a unique identifier for the user. However, override as
         * necessary.
         */
//        'sub' => [
//            'attribute-defined-in-useridattr', // will be dynamically added if the list for 'sub' claim is not set.
//            'eduPersonPrincipalName',
//            'eduPersonTargetedID',
//            'eduPersonUniqueId',
//        ],
//        'name' => [
//            'cn',
//            'displayName',
//        ],
//        'family_name' => [
//            'sn',
//        ],
//        'given_name' => [
//            'givenName',
//        ],
//        'middle_name' => [
//            // Empty
//        ],
//        'nickname' => [
//            'eduPersonNickname',
//        ],
//        'preferred_username' => [
//            'uid',
//        ],
//        'profile' => [
//            'labeledURI',
//            'description',
//        ],
//        'picture' => [
//            // Empty. Previously 'jpegPhoto' however, spec calls for a URL to a photo, not an actual photo.
//        ],
//        'website' => [
//            // Empty
//        ],
//        'gender' => [
//            // Empty
//        ],
//        'birthdate' => [
//            // Empty
//        ],
//        'zoneinfo' => [
//            // Empty
//        ],
//        'locale' => [
//            'preferredLanguage',
//        ],
//        'updated_at' => [
//            'type' => 'int',
//            'attributes' => [],
//        ],
//        'email' => [
//            'mail',
//        ],
//        'email_verified' => [
//            'type' => 'bool',
//            'attributes' => [],
//        ],
//         // address is a JSON object. Set the 'formatted' subclaim to postalAddress
//        'address' => [
//            'type' => 'json',
//            'claims' => [
//                'formatted' => ['postalAddress'],
//            ]
//        ],
//        'phone_number' => [
//            'mobile',
//            'telephoneNumber',
//            'homePhone',
//        ],
//        'phone_number_verified' => [
//            'type' => 'bool',
//            'attributes' => [],
//        ],
        /*
         * Optional scopes attributes
         */
//        'national_document_id' => [
//            'schacPersonalUniqueId',
//        ],
    ],

    /**
     * Optional custom scopes. You can create as many scopes as you want and
     * assign claims to them.
     */
    ModuleConfig::OPTION_AUTH_CUSTOM_SCOPES => [
//        'private' => [ // The key represents the scope name.
//            'description' => 'private scope',
//            'claim_name_prefix' => '', // Prefix to apply for all claim names from this scope
//            'are_multiple_claim_values_allowed' => false, // Are claims for this scope allowed to have multiple values
//            'claims' => ['national_document_id'] // Claims from the translation table which this scope will contain
//        ],
    ],

    /**
     * Optional list of the Authentication Context Class References that this OP
     * supports. If populated, this list will be available in the OP discovery
     * document (OP Metadata) as 'acr_values_supported'.
     * @see https://datatracker.ietf.org/doc/html/rfc6711
     * @see https://www.iana.org/assignments/loa-profiles/loa-profiles.xhtml
     * @see https://openid.net/specs/openid-connect-core-1_0.html#IDToken (acr claim)
     * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest (acr_values parameter)
     * Syntax: string[] (array of strings)
     */
    ModuleConfig::OPTION_AUTH_ACR_VALUES_SUPPORTED => [
//        'https://refeds.org/assurance/profile/espresso',
//        'https://refeds.org/assurance/profile/cappuccino',
//        'https://refeds.org/profile/mfa',
//        'https://refeds.org/profile/sfa',
//        'urn:mace:incommon:iap:silver',
//        'urn:mace:incommon:iap:bronze',
//        '4',
//        '3',
//        '2',
//        '1',
//        '0',
//        '...',
    ],

    /**
     * If this OP supports ACRs, indicate which usable auth source supports
     * which ACRs. Order of ACRs is important, more important ones being first.
     * Syntax: array<string,string[]> (array with an auth source as a key and
     * value being array of ACR values as strings)
     */

    ModuleConfig::OPTION_AUTH_SOURCES_TO_ACR_VALUES_MAP => [
//        'example-userpass' => ['1', '0'],
//        'default-sp' => ['http://id.incommon.org/assurance/bronze', '2', '1', '0'],
//        'strongly-assured-authsource' => [
//            'https://refeds.org/assurance/profile/espresso',
//            'https://refeds.org/profile/mfa',
//            'https://refeds.org/assurance/profile/cappuccino',
//            'https://refeds.org/profile/sfa',
//            '3',
//            '2',
//            '1',
//            '0',
//        ],
    ],

    /**
     * If this OP supports ACRs, indicate if authentication using cookie should
     * be forced to specific ACR value. If this option is set to null, no
     * specific ACR will be forced for cookie authentication, and the resulting
     * ACR will be one of the ACRs supported on a used auth source during
     * authentication, that is, session creation. If this option is set to
     * a specific ACR, with ACR value being one of the ACR values this OP
     * supports, it will be set to that ACR for cookie authentication.
     * For example, OIDC Core Spec notes that authentication using a long-lived
     * browser cookie is one example where the use of "level 0" is appropriate.
     */
//     ModuleConfig::OPTION_AUTH_FORCED_ACR_VALUE_FOR_COOKIE_AUTHENTICATION => '0',
    ModuleConfig::OPTION_AUTH_FORCED_ACR_VALUE_FOR_COOKIE_AUTHENTICATION => null,

    /**
     * Choose if an OP discovery document will include the 'claims_supported'
     * claim, which is recommended per OpenID Connect Discovery specification
     * https://openid.net/specs/openid-connect-discovery-1_0.html. The list will
     * include all claims for which "SAML attribute to OIDC claim translation"
     * has been defined above.
     */
    ModuleConfig::OPTION_PROTOCOL_DISCOVERY_SHOW_CLAIMS_SUPPORTED => false,

    /**
     * Settings regarding Authentication Processing Filters.
     * Note: An OIDC authN state array will not contain all the keys which are
     * available during SAML authN, like Service Provider metadata, etc.
     *
     * At the moment, the following SAML authN data will be available during
     * OIDC authN in the state array:
     * - ['Attributes'], ['Authority'], ['AuthnInstant'], ['Expire']
     * Source and destination will have entity IDs corresponding to the OP
     * issuer ID and Client ID respectively.
     * - ['Source']['entityid'] - contains OpenId Provider issuer ID
     * - ['Destination']['entityid'] - contains Relying Party (OIDC Client) ID
     * In addition to that, the following OIDC related data will be available
     * in the state array:
     * - ['Oidc']['OpenIdProviderMetadata'] - contains information otherwise
     * available from the OIDC configuration URL.
     * - ['Oidc']['RelyingPartyMetadata'] - contains information about the OIDC
     * client making the authN request.
     * - ['Oidc']['AuthorizationRequestParameters'] - contains relevant
     * authorization request query parameters.
     *
     * List of authproc filters which will run for every OIDC authN. Add filters
     * as described in docs for SAML authproc.
     * @see https://simplesamlphp.org/docs/stable/simplesamlphp-authproc
     */
    ModuleConfig::OPTION_AUTH_PROCESSING_FILTERS => [
        // Add authproc filters here
    ],

    /**
     * (optional) Dedicated OIDC protocol cache adapter, used to cache artifacts
     * like access tokens, authorization codes, refresh tokens, client data,
     * user data, etc. It will also be used for token reuse check in the
     * protocol context. Setting this option is recommended in production
     * environments. If set to null, no caching will be used. Can be set to
     * any Symfony Cache Adapter class, like in the examples below. If set,
     * make sure to also give proper adapter arguments for its instantiation
     * below.
     * @see https://symfony.com/doc/current/components/cache.html#available-cache-adapters
     */
    ModuleConfig::OPTION_PROTOCOL_CACHE_ADAPTER => null,
//    ModuleConfig::OPTION_PROTOCOL_CACHE_ADAPTER => \Symfony\Component\Cache\Adapter\FilesystemAdapter::class,
//    ModuleConfig::OPTION_PROTOCOL_CACHE_ADAPTER => \Symfony\Component\Cache\Adapter\MemcachedAdapter::class,

    /**
     * Protocol cache adapter arguments used for adapter instantiation. Refer
     * to documentation for a particular adapter on which arguments are needed
     * to create its instance, in the order of constructor arguments. See
     * examples below.
     */
    ModuleConfig::OPTION_PROTOCOL_CACHE_ADAPTER_ARGUMENTS => [
        // Adapter arguments here...
    ],
    // Example for FileSystemAdapter:
//    ModuleConfig::OPTION_PROTOCOL_CACHE_ADAPTER_ARGUMENTS => [
//        'openidFederation', // Namespace, subdirectory of main cache directory
//        60 * 60 * 6, // Default lifetime in seconds (used when a particular cache item doesn't define its own lifetime)
//        '/path/to/main/cache/directory' // Must be writable. Can be set to null to use the system temporary directory.
//    ],
//     Example for MemcachedAdapter:
//    ModuleConfig::OPTION_PROTOCOL_CACHE_ADAPTER_ARGUMENTS => [
//        // First argument is a connection instance, so we can use the helper method to create it. In this example a
//        // single server is used. Refer to documentation on how to use multiple servers and / or to provide other
//        // options.
//        \Symfony\Component\Cache\Adapter\MemcachedAdapter::createConnection(
//            'memcached://localhost'
//        // the DSN can include config options (pass them as a query string):
//        // 'memcached://localhost:11222?retry_timeout=10'
//        // 'memcached://localhost:11222?socket_recv_size=1&socket_send_size=2'
//        ),
//        'openidProtocol', // Namespace, key prefix.
//        60 * 60 * 6, // Default lifetime in seconds (used when a particular cache item doesn't define its own lifetime)
//    ],

    /**
     * Protocol cache duration for user entities (authenticated users data).
     * If not set, cache duration will be the same as session duration.
     * This is only relevant if a protocol cache adapter is set up. For duration
     * format info, check
     * https://www.php.net/manual/en/dateinterval.construct.php.
     */
//    ModuleConfig::OPTION_PROTOCOL_USER_ENTITY_CACHE_DURATION => 'PT1H', // 1 hour
    ModuleConfig::OPTION_PROTOCOL_USER_ENTITY_CACHE_DURATION => null, // Fallback to session duration
    /**
     * Protocol cache duration for client entities, with a given default.
     * This is only relevant if a protocol cache adapter is set up. For duration
     * format info, check
     * https://www.php.net/manual/en/dateinterval.construct.php.
     */
    ModuleConfig::OPTION_PROTOCOL_CLIENT_ENTITY_CACHE_DURATION => 'PT10M', // 10 minutes

    /**
     * Note: cache duration for Authorization Code, Access Token, and Refresh
     * Token will fall back to their TTL.
     */

    /**
     * Cron tag used to run a storage cleanup script using the cron module.
     */
    ModuleConfig::OPTION_CRON_TAG => 'hourly',

    /**
     * Permissions which let the module expose functionality to specific users.
     * In the below configuration, a user's eduPersonEntitlement attribute is
     * examined. If the user tries to do something that requires the 'client'
     * permission (such as registering their own client), then they will need
     * one of the eduPersonEntitlements from the `client` permission array.
     * A permission can be disabled by commenting it out.
     */
    ModuleConfig::OPTION_ADMIN_UI_PERMISSIONS => [
        // Attribute to inspect to determine user's permissions
        'attribute' => 'eduPersonEntitlement',
        // Which entitlements allow for registering, editing, deleting a client?
        // The creator owns OIDC clients
        'client' => ['urn:example:oidc:manage:client'],
    ],

    /**
     * Pagination options, for example, on the client listing page.
     */
    ModuleConfig::OPTION_ADMIN_UI_PAGINATION_ITEMS_PER_PAGE => 20,

    /***************************************************************************
     * (optional) OpenID Federation-related options. If these are not set,
     * OpenID Federation capabilities will be disabled.
     **************************************************************************/

    /**
     * Enable or disable federation capabilities. Default is disabled (false).
     */
    ModuleConfig::OPTION_FEDERATION_ENABLED => false,

    /**
     * Federation signature algorithm and key-pair definitions, representing
     * supported algorithms for signing, for example, Entity Statements.
     * The first algorithm in the list will be used for signing (the
     * first entry represents the default algorithm and signing key).
     * You can also use this config option to advertise any (new) keys, for
     * example, for key-rollover scenarios. Add those entries later in
     * the list, so they can be published in Federation JWKS.
     *
     * Note that these keys SHOULD NOT be the same as the ones used in the
     * protocol (Connect) itself.
     *
     * The format is the same as for the protocol (Connect) signature key pairs
     * (option ModuleConfig::OPTION_PROTOCOL_SIGNATURE_KEY_PAIRS)
     */
    ModuleConfig::OPTION_FEDERATION_SIGNATURE_KEY_PAIRS => [
        [
            ModuleConfig::KEY_ALGORITHM => \SimpleSAML\OpenID\Algorithms\SignatureAlgorithmEnum::RS256,
            ModuleConfig::KEY_PRIVATE_KEY_FILENAME => 'oidc_module_federation_rsa_01.key',
            ModuleConfig::KEY_PUBLIC_KEY_FILENAME => 'oidc_module_federation_rsa_01.pub',
//            ModuleConfig::KEY_PRIVATE_KEY_PASSWORD => 'private-key-password', // Optional
//            ModuleConfig::KEY_KEY_ID => 'rsa-federation-signing-key-01', // Optional
        ],
    ],

    /**
     * Trust Anchors which are valid for this entity. The key represents the
     * Trust Anchor Entity ID, while the value can be the Trust Anchor's JWKS
     * JSON object string value, or null. If JWKS is provided, it will be used
     * to validate Trust Anchor Configuration Statement in addition to using
     * JWKS acquired during Trust Chain resolution. If JWKS is not provided
     * (value null), the validity of Trust Anchor Configuration Statement will
     * "only" be validated by the JWKS acquired during Trust Chain resolution,
     * meaning that security will rely "only" on protection implied from using
     * TLS on endpoints used during Trust Chain resolution.
     */
    ModuleConfig::OPTION_FEDERATION_TRUST_ANCHORS => [
        // phpcs:ignore
//        'https://ta.example.org/' => '{"keys":[{"kty": "RSA","alg": "RS256","use": "sig","kid": "Nzb...9Xs","e": "AQAB","n": "pnXB...ub9J"}]}',
//        'https://ta2.example.org/' => null,
    ],

    /**
     * Federation authority hints. An array of strings representing the Entity
     * Identifiers of Intermediate Entities (or Trust Anchors). Required if
     * this entity has a Superior entity above it.
     */
    ModuleConfig::OPTION_FEDERATION_AUTHORITY_HINTS => [
//        'https://intermediate.example.org/',
    ],

    /**
     * (optional) Federation Trust Mark tokens. An array of tokens
     * (signed JWTs), each representing a Trust Mark  issued to this entity.
     * This option is primarily intended for long-lasting or non-expiring
     * tokens, so it is not necessary to dynamically fetch / refresh them.
     */
    ModuleConfig::OPTION_FEDERATION_TRUST_MARK_TOKENS => [
//        'eyJ...GHg',
    ],

    /**
     * (optional) Federation Trust Marks for dynamic fetching. An array of
     * key-value pairs, where key is Trust Mark Type and value is Trust Mark
     * Issuer ID, each representing a Trust Mark issued to this entity. Each
     * Trust Mark Type in this array will be dynamically fetched from the noted
     * Trust Mark Issuer as necessary. If federation caching is enabled
     * (recommended), fetched Trust Marks will also be cached until their
     * expiry.
     */
    ModuleConfig::OPTION_FEDERATION_DYNAMIC_TRUST_MARKS => [
//        'trust-mark-type' => 'trust-mark-issuer-id',
    ],

    /**
     * (optional) Federation participation limit by Trust Marks. This is an
     * array with the following format:
     *  [
     *     'trust-anchor-id' => [
     *          'limit-id' => [
     *               'trust-mark-type',
     *               'trust-mark-type-2',
     *           ],
     *      ],
     *  ],
     * Check the example below on how this can be used. If a federation
     * participation limit is configured for a particular Trust Anchor ID, at
     * least one combination of "limit ID" => "trust mark list" should be
     * defined.
     */
    ModuleConfig::OPTION_FEDERATION_PARTICIPATION_LIMIT_BY_TRUST_MARKS => [
        // We are limiting federation participation using Trust Marks for
        // 'https://ta.example.org/'.
        'https://ta.example.org/' => [
            // Entities must have (at least) one Trust Mark from the list below.
            \SimpleSAML\Module\oidc\Codebooks\LimitsEnum::OneOf->value => [
                'trust-mark-type',
                'trust-mark-type-2',
            ],
            // Entities must have all Trust Marks from the list below.
            \SimpleSAML\Module\oidc\Codebooks\LimitsEnum::AllOf->value => [
                'trust-mark-type-3',
                'trust-mark-type-4',
            ],
        ],
    ],

    /**
     * (optional) Trust Mark Status Endpoint Usage Policy. Check the
     * TrustMarkStatusEndpointUsagePolicyEnum for the available options. Default
     * is RequiredIfEndpointProvidedForNonExpiringTrustMarksOnly, meaning that
     * the Trust Mark Status Endpoint will be used to check the status of
     * non-expiring Trust Marks if the Trust Mark Status Endpoint is provided
     * by the Trust Mark Issuer.
     */
    ModuleConfig::OPTION_FEDERATION_TRUST_MARK_STATUS_ENDPOINT_USAGE_POLICY =>
        \SimpleSAML\OpenID\Codebooks\TrustMarkStatusEndpointUsagePolicyEnum::RequiredIfEndpointProvidedForNonExpiringTrustMarksOnly,

    /**
     * (optional) Dedicated federation cache adapter, used to cache federation
     * artifacts like trust chains, entity statements, etc. It will also be
     * used for token reuse check in federation context. Setting this option is
     * recommended in production environments. If set to null, no caching will
     * be used. Can be set to any Symfony Cache Adapter class. If set, make
     * sure to also give proper adapter arguments for its instantiation below.
     * See examples for a protocol cache adapter option.
     * @see https://symfony.com/doc/current/components/cache.html#available-cache-adapters
     */
    ModuleConfig::OPTION_FEDERATION_CACHE_ADAPTER => null,

    /**
     * Federation cache adapter arguments used for adapter instantiation. Refer
     * to documentation for a particular adapter on which arguments are needed
     * to create its instance, in the order of constructor arguments.
     * See examples for a protocol cache adapter option.
     */
    ModuleConfig::OPTION_FEDERATION_CACHE_ADAPTER_ARGUMENTS => [
        // Adapter arguments here...
    ],

    /**
     * Maximum federation cache duration for fetched artifacts. Federation cache
     * duration will typically be resolved based on the expiry of the fetched
     * artifact. For example, when caching fetched entity statements, cache
     * duration will be based on the 'exp' claim (expiration time). Since those
     * claims are set by issuer (can be long), it could be desirable to limit
     * the maximum time so that items in the cache get refreshed more regularly
     * (and changes propagate more quickly). This is only relevant if a
     * federation cache adapter is set up. For duration format info, check
     * https://www.php.net/manual/en/dateinterval.construct.php.
     */
    ModuleConfig::OPTION_FEDERATION_CACHE_MAX_DURATION_FOR_FETCHED => 'PT6H', // 6 hours

    /**
     * Federation entity statement duration which determines the Expiration Time
     * (exp) claim set in entity statement JWSs published by this OP. If not
     * set, a default of 1 day will be used. For duration format info, check
     * https://www.php.net/manual/en/dateinterval.construct.php
     */
    ModuleConfig::OPTION_FEDERATION_ENTITY_STATEMENT_DURATION => 'P1D', // 1 day

    /**
     * Cache duration for federation entity statements produced by this OP.
     * This can be used to avoid calculating JWS signature on every HTTP request
     * for an OP Configuration statement, Subordinate Statements... This is only
     * relevant if a federation cache adapter is set up. For duration format
     * info, check https://www.php.net/manual/en/dateinterval.construct.php.
     */
    ModuleConfig::OPTION_FEDERATION_CACHE_DURATION_FOR_PRODUCED => 'PT2M', // 2 minutes

    /**
     * Common federation entity parameters:
     * https://openid.net/specs/openid-federation-1_0.html#name-common-metadata-parameters
     */
    ModuleConfig::OPTION_ORGANIZATION_NAME => null,
    ModuleConfig::OPTION_DISPLAY_NAME => null,
    ModuleConfig::OPTION_DESCRIPTION => null,
    ModuleConfig::OPTION_KEYWORDS => [
        // 'some-keyword',
    ],
    ModuleConfig::OPTION_CONTACTS => [
        // 'John Doe jdoe@example.org',
    ],
    ModuleConfig::OPTION_LOGO_URI => null,
    ModuleConfig::OPTION_POLICY_URI => null,
    ModuleConfig::OPTION_INFORMATION_URI => null,
    ModuleConfig::OPTION_ORGANIZATION_URI => null,


    /***************************************************************************
     * (optional) OpenID Verifiable Credential related options. If these are
     * not set, OpenID Verifiable Credential capabilities will be disabled.
     **************************************************************************/

    /**
     * Enable or disable verifiable credentials capabilities. Default is
     * disabled (false).
     */
    ModuleConfig::OPTION_VCI_ENABLED => false,

    /**
     * Verifiable Credential signature algorithm and key-pair definitions,
     * representing supported algorithms for signing verifiable credentials.
     * The first algorithm in the list will be used for signing (the
     * first entry represents the default algorithm and signing key).
     * You can also use this config option to advertise any (new) keys, for
     * example, for key-rollover scenarios. Add those entries later in
     * the list, so they can be published in appropriate JWKS.
     *
     * Note that these keys SHOULD NOT be the same as the ones used in the
     * protocol (Connect) itself.
     *
     * The format is the same as for the protocol (Connect) signature key pairs
     * (option ModuleConfig::OPTION_PROTOCOL_SIGNATURE_KEY_PAIRS)
     *
     * NOTE: for the time being, only one key-pair is supported.
     */
    ModuleConfig::OPTION_VCI_SIGNATURE_KEY_PAIRS => [
        [
            ModuleConfig::KEY_ALGORITHM => \SimpleSAML\OpenID\Algorithms\SignatureAlgorithmEnum::ES256,
            ModuleConfig::KEY_PRIVATE_KEY_FILENAME => 'oidc_module_vci_ec_p256_01.key',
            ModuleConfig::KEY_PUBLIC_KEY_FILENAME => 'oidc_module_vci_ec_p256_01.pub',
//            ModuleConfig::KEY_PRIVATE_KEY_PASSWORD => 'private-key-password', // Optional
//            ModuleConfig::KEY_KEY_ID => 'ec-vci-signing-key-01', // Optional
        ],
    ],

    /**
     * Allow or disallow non-registered clients to request verifiable
     * credentials. Default is disallowed (false).
     */
    ModuleConfig::OPTION_VCI_ALLOW_NON_REGISTERED_CLIENTS => false,

    /**
     * Allowed redirect URI prefixes for non-registered clients. By default,
     * this is set to
     * 'openid-credential-offer://' to allow only redirect URIs with this prefix.
     *
     * Example:
     *  [
     *      'https://example.org/redirect',
     *      'https://example.org/redirect2',
     *  ]
     */
    ModuleConfig::OPTION_VCI_ALLOWED_REDIRECT_URI_PREFIXES_FOR_NON_REGISTERED_CLIENTS => [
        'openid-credential-offer://',
    ],

    /**
     * (optional) Credential configuration statements, as per
     * `credential_configurations_supported` claim definition in
     * https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#credential-issuer-parameters.
     * Check the example below on how this can be used.
     */
    ModuleConfig::OPTION_VCI_CREDENTIAL_CONFIGURATIONS_SUPPORTED => [
        // Sample for 'jwt_vc_json' format with notes about required and
        // optional fields.
        'ResearchAndScholarshipCredentialJwtVcJson' => [
            // REQUIRED
            ClaimsEnum::Format->value => CredentialFormatIdentifiersEnum::JwtVcJson->value,
            // OPTIONAL
            ClaimsEnum::Scope->value => 'ResearchAndScholarshipCredentialJwtVcJson',

            // OPTIONAL
            // cryptographic_binding_methods_supported

            // OPTIONAL - will be set / overridden to the protocol signing
            // algorithm.
            // credential_signing_alg_values_supported

            // OPTIONAL
            // proof_types_supported

            // OPTIONAL
            // cryptographic_binding_methods_supported

            ClaimsEnum::Display->value => [
                [
                    ClaimsEnum::Name->value => 'ResearchAndScholarshipCredentialJwtVcJson',
                    ClaimsEnum::Locale->value => 'en-US',

                    // OPTIONAL
                    // logo

                    // OPTIONAL
                    ClaimsEnum::Description->value => 'Research and Scholarship Credential',

                    // OPTIONAL
                    // background_color

                    // OPTIONAL
                    // background_image

                    // OPTIONAL
                    // text_color
                ],
            ],

            // OPTIONAL A.1.1.2. https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-vc-signed-as-a-jwt-not-usin
            ClaimsEnum::Claims->value => [
                /**
                 * https://refeds.org/category/research-and-scholarship
                 *
                 * The R&S attribute bundle consists (abstractly) of the
                 * following required data elements:
                 *
                 * shared user identifier
                 * person name
                 * email address
                 *
                 * and one optional data element:
                 *
                 * affiliation
                 *
                 * where shared user identifier is a persistent, non-reassigned,
                 * non-targeted identifier defined to be either of the
                 * following:
                 *
                 * eduPersonPrincipalName (if non-reassigned)
                 * eduPersonPrincipalName + eduPersonTargetedID
                 *
                 * and where person name is defined to be either (or both) of
                 * the following:
                 *
                 * displayName
                 * givenName + sn
                 *
                 * and where email address is defined to be the mail attribute,
                 * and where affiliation is defined to be the
                 * eduPersonScopedAffiliation attribute.
                 *
                 * All of the above attributes are defined or referenced in the
                 * [eduPerson] specification. The specific naming and format of
                 * these attributes is guided by the protocol in use. For SAML
                 * 2.0 the [SAMLAttr] profile MUST be used. This specification
                 * may be extended to reference other protocol-specific
                 * formulations as circumstances warrant.
                 */
                [
                    // REQUIRED
                    ClaimsEnum::Path->value => [ClaimsEnum::Credential_Subject->value, 'eduPersonPrincipalName'],
                    // OPTIONAL
                    ClaimsEnum::Mandatory->value => true,
                    // OPTIONAL
                    ClaimsEnum::Display->value => [
                        [
                            // OPTIONAL
                            ClaimsEnum::Name->value => 'Principal Name',
                            // OPTIONAL
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => [ClaimsEnum::Credential_Subject->value, 'eduPersonTargetedID'],
                    ClaimsEnum::Mandatory->value => false,
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Targeted ID',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => [ClaimsEnum::Credential_Subject->value, 'displayName'],
                    ClaimsEnum::Mandatory->value => false,
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Display Name',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => [ClaimsEnum::Credential_Subject->value, 'givenName'],
                    ClaimsEnum::Mandatory->value => false,
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Given Name',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => [ClaimsEnum::Credential_Subject->value, 'sn'],
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Last Name',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => [ClaimsEnum::Credential_Subject->value, 'mail'],
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Email Address',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => [ClaimsEnum::Credential_Subject->value, 'eduPersonScopedAffiliation'],
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Scoped Affiliation',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
            ],

            // REQUIRED
            ClaimsEnum::CredentialDefinition->value => [
                ClaimsEnum::Type->value => [
                    CredentialTypesEnum::VerifiableCredential->value,
                    'ResearchAndScholarshipCredentialJwtVcJson',
                ],
            ],
        ],

        // Sample for 'dc+sd-jwt' format without notes about required and
        // optional fields.
        'ResearchAndScholarshipCredentialDcSdJwt' => [
            ClaimsEnum::Format->value => CredentialFormatIdentifiersEnum::DcSdJwt->value,
            // In earlier drafts it was vc+sd-jwt.
            //ClaimsEnum::Format->value => CredentialFormatIdentifiersEnum::VcSdJwt->value,
            ClaimsEnum::Scope->value => 'ResearchAndScholarshipCredentialDcSdJwt',
            ClaimsEnum::Display->value => [
                [
                    ClaimsEnum::Name->value => 'ResearchAndScholarshipCredentialDcSdJwt',
                    ClaimsEnum::Locale->value => 'en-US',
                    ClaimsEnum::Description->value => 'Research and Scholarship Credential',
                ],
            ],
            ClaimsEnum::Claims->value => [
                [
                    ClaimsEnum::Path->value => ['eduPersonPrincipalName'],
                    ClaimsEnum::Mandatory->value => true,
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Principal Name',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => ['eduPersonTargetedID'],
                    ClaimsEnum::Mandatory->value => false,
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Targeted ID',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => ['displayName'],
                    ClaimsEnum::Mandatory->value => false,
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Display Name',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => ['givenName'],
                    ClaimsEnum::Mandatory->value => false,
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Given Name',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => ['sn'],
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Last Name',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => ['mail'],
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Email Address',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
                [
                    ClaimsEnum::Path->value => ['eduPersonScopedAffiliation'],
                    ClaimsEnum::Display->value => [
                        [
                            ClaimsEnum::Name->value => 'Scoped Affiliation',
                            ClaimsEnum::Locale->value => LanguageTagsEnum::EnUs->value,
                        ],
                    ],
                ],
            ],

            // REQUIRED
            ClaimsEnum::Vct->value => 'ResearchAndScholarshipCredentialDcSdJwt',
        ],
    ],

    /**
     * Mapping of user attributes to a credential claim path, per credential
     * configuration ID. Note that the path must be present in the credential
     * configuration supported above. This is an array of arrays, with the
     * following format:
     *  [
     *     'credential-configuration-id' => [
     *          ['user-attribute-name' => ['path-element', 'path-element', ...]],
     *          '...',
     *      ],
     *  ],
     */
    ModuleConfig::OPTION_VCI_USER_ATTRIBUTE_TO_CREDENTIAL_CLAIM_PATH_MAP => [
        'ResearchAndScholarshipCredentialJwtVcJson' => [
            ['eduPersonPrincipalName' => [ClaimsEnum::Credential_Subject->value, 'eduPersonPrincipalName']],
            ['eduPersonTargetedID' => [ClaimsEnum::Credential_Subject->value, 'eduPersonTargetedID']],
            ['displayName' => [ClaimsEnum::Credential_Subject->value, 'displayName']],
            ['givenName' => [ClaimsEnum::Credential_Subject->value, 'givenName']],
            ['sn' => [ClaimsEnum::Credential_Subject->value, 'sn']],
            ['mail' => [ClaimsEnum::Credential_Subject->value, 'mail']],
            ['eduPersonScopedAffiliation' => [ClaimsEnum::Credential_Subject->value, 'eduPersonScopedAffiliation']],
        ],
        'ResearchAndScholarshipCredentialDcSdJwt' => [
            ['eduPersonPrincipalName' => ['eduPersonPrincipalName']],
            ['eduPersonTargetedID' => ['eduPersonTargetedID']],
            ['displayName' => ['displayName']],
            ['givenName' => ['givenName']],
            ['sn' => ['sn']],
            ['mail' => ['mail']],
            ['eduPersonScopedAffiliation' => ['eduPersonScopedAffiliation']],
        ],
    ],

    /**
     * (optional) Issuer State TTL (validity duration), with the given example.
     * If not set, falls back to Authorization Code TTL. For duration format
     * info, check https://www.php.net/manual/en/dateinterval.construct.php
     */
    ModuleConfig::OPTION_VCI_ISSUER_STATE_TTL => 'PT10M', // 10 minutes

    /**
     * Map of authentication sources and user's email attribute names. This
     * enables you to define a specific attribute name which contains the
     * user's email address, per authentication source. This is used, for
     * example, to send Transaction Code in the case of pre-authorized
     * codes for Verifiable Credential Issuance. If not set, the default
     * user's email attribute name will be used (see the option below).
     *
     * Format is: 'authentication-source-id' => 'email-attribute-name'.
     */
    ModuleConfig::OPTION_AUTH_SOURCES_TO_USERS_EMAIL_ATTRIBUTE_NAME_MAP => [
        'example-auth-source-id' => 'mail',
    ],

    /**
     * The default name of the attribute which contains the user's email
     * address. If not set, it will fall back to 'mail'.
     */
    ModuleConfig::OPTION_DEFAULT_USERS_EMAIL_ATTRIBUTE_NAME => 'mail',


    /***************************************************************************
     * (optional) API-related options.
     **************************************************************************/

    /**
     * (optional) Enable or disable API capabilities. Default is disabled
     * (false). If API capabilities are enabled, you can enable or disable
     * specific API endpoints as needed and set up API tokens to allow
     * access to those endpoints. If API capabilities are disabled, all API
     * endpoints will be inaccessible regardless of the settings for
     * specific endpoints and API tokens.
     *
     */
    ModuleConfig::OPTION_API_ENABLED => false,

    /**
     * (optional) API Enable VCI Credential Offer API endpoint. Default is
     * disabled (false). Only relevant if API capabilities are enabled.
     */
    ModuleConfig::OPTION_API_VCI_CREDENTIAL_OFFER_ENDPOINT_ENABLED => false,

    /**
     * (optional) API Enable OAuth2 Token Introspection API endpoint. Default
     * is disabled (false). Only relevant if API capabilities are enabled.
     */
    ModuleConfig::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_ENDPOINT_ENABLED => false,

    /**
     * List of API tokens which can be used to access API endpoints based on
     * given scopes. The format is: ['token' => [ApiScopesEnum]]
     */
    ModuleConfig::OPTION_API_TOKENS => [
//        'strong-random-token-string' => [
//            \SimpleSAML\Module\oidc\Codebooks\ApiScopesEnum::All, // Gives access to the whole API.
//            \SimpleSAML\Module\oidc\Codebooks\ApiScopesEnum::VciAll, // Gives access to all VCI-related endpoints.
//            \SimpleSAML\Module\oidc\Codebooks\ApiScopesEnum::VciCredentialOffer, // Gives access to the credential offer endpoint.
//        ],
//        'strong-random-token-string-2' => [
//            \SimpleSAML\Module\oidc\Codebooks\ApiScopesEnum::All, // Gives access to the whole API.
//            \SimpleSAML\Module\oidc\Codebooks\ApiScopesEnum::OAuth2All, // Gives access to all OAuth2-related endpoints.
//            \SimpleSAML\Module\oidc\Codebooks\ApiScopesEnum::OAuth2TokenIntrospection, // Gives access to the token introspection endpoint.
//        ],
    ],
];