Function startAuthorization

src/client/auth.ts:1114–1181

(
    authorizationServerUrl: string | URL,
    {
        metadata,
        clientInformation,
        redirectUrl,
        scope,
        state,
        resource
    }: {
        metadata?: AuthorizationServerMetadata;
        clientInformation: OAuthClientInformationMixed;
        redirectUrl: string | URL;
        scope?: string;
        state?: string;
        resource?: URL;
    }
)

 * Begins the authorization flow with the given server, by generating a PKCE challenge and constructing the authorization URL.
 */
export async function startAuthorization(
    authorizationServerUrl: string | URL,
    {
        metadata,
        clientInformation,
        redirectUrl,
        scope,
        state,
        resource
    }: {
        metadata?: AuthorizationServerMetadata;
        clientInformation: OAuthClientInformationMixed;
        redirectUrl: string | URL;
        scope?: string;
        state?: string;
        resource?: URL;
    }
): Promise<{ authorizationUrl: URL; codeVerifier: string }> {
    let authorizationUrl: URL;
    if (metadata) {
        authorizationUrl = new URL(metadata.authorization_endpoint);

        if (!metadata.response_types_supported.includes(AUTHORIZATION_CODE_RESPONSE_TYPE)) {
            throw new Error(`Incompatible auth server: does not support response type ${AUTHORIZATION_CODE_RESPONSE_TYPE}`);
        }

        if (
            metadata.code_challenge_methods_supported &&
            !metadata.code_challenge_methods_supported.includes(AUTHORIZATION_CODE_CHALLENGE_METHOD)
        ) {
            throw new Error(`Incompatible auth server: does not support code challenge method ${AUTHORIZATION_CODE_CHALLENGE_METHOD}`);
        }
    } else {
        authorizationUrl = new URL('/authorize', authorizationServerUrl);
    }

    // Generate PKCE challenge
    const challenge = await pkceChallenge();
    const codeVerifier = challenge.code_verifier;
    const codeChallenge = challenge.code_challenge;

    authorizationUrl.searchParams.set('response_type', AUTHORIZATION_CODE_RESPONSE_TYPE);
    authorizationUrl.searchParams.set('client_id', clientInformation.client_id);
    authorizationUrl.searchParams.set('code_challenge', codeChallenge);
    authorizationUrl.searchParams.set('code_challenge_method', AUTHORIZATION_CODE_CHALLENGE_METHOD);
    authorizationUrl.searchParams.set('redirect_uri', String(redirectUrl));

    if (state) {
        authorizationUrl.searchParams.set('state', state);
    }

    if (scope) {
        authorizationUrl.searchParams.set('scope', scope);
    }

    if (scope?.includes('offline_access')) {
        // if the request includes the OIDC-only "offline_access" scope,
        // we need to set the prompt to "consent" to ensure the user is prompted to grant offline access