<!--
This file was generated by Spark. Do not edit it by hand.
-->
# AshAuthentication.Strategy.Microsoft

Strategy for authenticating using [Microsoft](https://microsoft.com)

This strategy builds on-top of `AshAuthentication.Strategy.Oidc` and
[`assent`](https://hex.pm/packages/assent).

It uses Microsoft's OpenID Connect discovery endpoint to automatically
retrieve token, authorization, and user info URLs. User identity claims
(email, name, etc.) are extracted from the ID token returned during the
authorization code flow.

In order to use Microsoft you need to provide the following minimum configuration:

  - `client_id`
  - `redirect_uri`
  - `client_secret`

By default the strategy uses the `common` tenant endpoint, which allows any
Microsoft account (personal, work, or school). Multi-tenant issuer validation
is handled automatically — the `{tenantid}` template in Microsoft's discovery
document is resolved from the ID token's `tid` claim before validation.

To restrict sign-in to a specific Azure tenant, override `base_url`:

    base_url "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0"

## More documentation:
- The [Microsoft OpenID Connect Overview](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc).
- The [Microsoft Tutorial](/documentation/tutorials/microsoft.md)
- The [OIDC documentation](`AshAuthentication.Strategy.Oidc`)


### authentication.strategies.microsoft
```elixir
microsoft name \\ :microsoft
```


Provides a pre-configured authentication strategy for [Microsoft](https://microsoft.com/).

This strategy is built using the `:oidc` strategy, and automatically
retrieves configuration from Microsoft's discovery endpoint
(`https://login.microsoftonline.com/{tenant|common}/v2.0/.well-known/openid-configuration`).

By default the strategy uses the `common` tenant endpoint. To restrict
sign-in to a specific Azure tenant, override `base_url`:

base_url "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0"

###### More documentation:
- The [Microsoft OpenID Connect Overview](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc)
- The [Microsoft Tutorial](/documentation/tutorials/microsoft.md)
- The [OIDC documentation](`AshAuthentication.Strategy.Oidc`)

###### Strategy defaults:

The following defaults are applied:

* `:base_url` is set to `"https://login.microsoftonline.com/common/v2.0"`.
* `:authorization_params` is set to `[scope: "email profile"]`.
* `:client_authentication_method` is set to `"client_secret_post"`.


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#authentication-strategies-microsoft-name){: #authentication-strategies-microsoft-name .spark-required} | `atom` |  | Uniquely identifies the strategy. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`client_id`](#authentication-strategies-microsoft-client_id){: #authentication-strategies-microsoft-client_id .spark-required} | `(any, any -> any) \| module \| String.t` |  | The OAuth2 client ID.  Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. |
| [`redirect_uri`](#authentication-strategies-microsoft-redirect_uri){: #authentication-strategies-microsoft-redirect_uri .spark-required} | `(any, any -> any) \| module \| String.t` |  | The callback URI *base*. Not the whole URI back to the callback endpoint, but the URI to your `AuthPlug`. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. |
| [`base_url`](#authentication-strategies-microsoft-base_url){: #authentication-strategies-microsoft-base_url } | `(any, any -> any) \| module \| String.t` | `"https://login.microsoftonline.com/common/v2.0"` | The base URL of the OAuth2 server - including the leading protocol (ie `https://`).  Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. |
| [`site`](#authentication-strategies-microsoft-site){: #authentication-strategies-microsoft-site } | `(any, any -> any) \| module \| String.t` |  | Deprecated: Use `base_url` instead. |
| [`prevent_hijacking?`](#authentication-strategies-microsoft-prevent_hijacking?){: #authentication-strategies-microsoft-prevent_hijacking? } | `boolean` | `true` | Requires a confirmation add_on to be present if the password strategy is used with the same identity_field. |
| [`auth_method`](#authentication-strategies-microsoft-auth_method){: #authentication-strategies-microsoft-auth_method } | `nil \| :client_secret_basic \| :client_secret_post \| :client_secret_jwt \| :private_key_jwt` | `:client_secret_post` | The authentication strategy used, optional. If not set, no authentication will be used during the access token request. |
| [`client_secret`](#authentication-strategies-microsoft-client_secret){: #authentication-strategies-microsoft-client_secret } | `(any, any -> any) \| module \| String.t` |  | The OAuth2 client secret. Required if :auth_method is `:client_secret_basic`, `:client_secret_post` or `:client_secret_jwt`. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. |
| [`trusted_audiences`](#authentication-strategies-microsoft-trusted_audiences){: #authentication-strategies-microsoft-trusted_audiences } | `(any, any -> any) \| module \| list(any) \| nil` |  | A list of audiences which are trusted. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. |
| [`private_key`](#authentication-strategies-microsoft-private_key){: #authentication-strategies-microsoft-private_key } | `(any, any -> any) \| module \| String.t` |  | The private key to use if `:auth_method` is `:private_key_jwt`. Takes either a module which implements the `AshAuthentication.Secret` behaviour, a 2 arity anonymous function or a string. |
| [`code_verifier`](#authentication-strategies-microsoft-code_verifier){: #authentication-strategies-microsoft-code_verifier } | `boolean` | `false` | Boolean to generate and use a random 128 byte long url safe code verifier for PKCE flow, optional, defaults to false. When set to true the session params will contain :code_verifier, :code_challenge, and :code_challenge_method params |
| [`authorization_params`](#authentication-strategies-microsoft-authorization_params){: #authentication-strategies-microsoft-authorization_params } | `(any, any -> any) \| module \| keyword \| nil` | `[scope: "email profile"]` | Any additional parameters to encode in the request phase. eg: `authorization_params scope: "openid profile email"` |
| [`registration_enabled?`](#authentication-strategies-microsoft-registration_enabled?){: #authentication-strategies-microsoft-registration_enabled? } | `boolean` | `true` | If enabled, new users will be able to register for your site when authenticating and not already present. If not, only existing users will be able to authenticate. |
| [`register_action_name`](#authentication-strategies-microsoft-register_action_name){: #authentication-strategies-microsoft-register_action_name } | `atom` |  | The name of the action to use to register a user, if `registration_enabled?` is `true`. Defaults to `register_with_<name>` See the "Registration and Sign-in" section of the strategy docs for more. |
| [`sign_in_action_name`](#authentication-strategies-microsoft-sign_in_action_name){: #authentication-strategies-microsoft-sign_in_action_name } | `atom` |  | The name of the action to use to sign in an existing user, if `sign_in_enabled?` is `true`. Defaults to `sign_in_with_<strategy>`, which is generated for you by default. See the "Registration and Sign-in" section of the strategy docs for more information. |
| [`identity_resource`](#authentication-strategies-microsoft-identity_resource){: #authentication-strategies-microsoft-identity_resource } | `module \| false` | `false` | The resource used to store user identities, or `false` to disable. See the User Identities section of the strategy docs for more. |
| [`identity_relationship_name`](#authentication-strategies-microsoft-identity_relationship_name){: #authentication-strategies-microsoft-identity_relationship_name } | `atom` | `:identities` | Name of the relationship to the provider identities resource |
| [`identity_relationship_user_id_attribute`](#authentication-strategies-microsoft-identity_relationship_user_id_attribute){: #authentication-strategies-microsoft-identity_relationship_user_id_attribute } | `atom` | `:user_id` | The name of the destination (user_id) attribute on your provider identity resource. Only necessary if you've changed the `user_id_attribute_name` option of the provider identity. |
| [`openid_configuration_uri`](#authentication-strategies-microsoft-openid_configuration_uri){: #authentication-strategies-microsoft-openid_configuration_uri } | `(any, any -> any) \| module \| String.t` | `"/.well-known/openid-configuration"` | The URI for the OpenID provider |
| [`client_authentication_method`](#authentication-strategies-microsoft-client_authentication_method){: #authentication-strategies-microsoft-client_authentication_method } | `"client_secret_basic" \| "client_secret_post" \| "client_secret_jwt" \| "private_key_jwt" \| "none"` | `"client_secret_post"` | The client authentication method to use. |
| [`openid_configuration`](#authentication-strategies-microsoft-openid_configuration){: #authentication-strategies-microsoft-openid_configuration } | `nil \| %{optional(String.t) => any}` |  | The OpenID configuration.  If not set, the configuration will be retrieved from `openid_configuration_uri`. |
| [`id_token_signed_response_alg`](#authentication-strategies-microsoft-id_token_signed_response_alg){: #authentication-strategies-microsoft-id_token_signed_response_alg } | `"HS256" \| "HS384" \| "HS512" \| "RS256" \| "RS384" \| "RS512" \| "ES256" \| "ES384" \| "ES512" \| "PS256" \| "PS384" \| "PS512" \| "Ed25519" \| "Ed25519ph" \| "Ed448" \| "Ed448ph" \| "EdDSA"` | `"RS256"` | The `id_token_signed_response_alg` parameter sent by the Client during Registration. |
| [`id_token_ttl_seconds`](#authentication-strategies-microsoft-id_token_ttl_seconds){: #authentication-strategies-microsoft-id_token_ttl_seconds } | `nil \| pos_integer` |  | The number of seconds from `iat` that an ID Token will be considered valid. |
| [`nonce`](#authentication-strategies-microsoft-nonce){: #authentication-strategies-microsoft-nonce } | `boolean \| (any, any -> any) \| module \| String.t` | `true` | A function for generating the session nonce, `true` to automatically generate it with `AshAuthentication.Strategy.Oidc.NonceGenerator`, or `false` to disable. |


### Introspection

Target: `AshAuthentication.Strategy.OAuth2`


<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>