ash_authentication/documentation/dsls/DSL:-AshAuthentication.Strategy.Github.md

DSL: AshAuthentication.Strategy.Github

Strategy for authenticating using GitHub

This strategy builds on-top of AshAuthentication.Strategy.OAuth2 and assent.

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

• client_id
• redirect_uri
• client_secret

See the GitHub quickstart guide for more information.

DSL Documentation

Provides a pre-configured authentication strategy for GitHub.

This strategy is built using the :oauth2 strategy, and thus provides all the same configuration options should you need them.

For more information see the Github Quick Start Guide in our documentation.

Strategy defaults:

The following defaults are applied:

• :base_url is set to "https://api.github.com".
• :authorize_url is set to "https://github.com/login/oauth/authorize".
• :token_url is set to "https://github.com/login/oauth/access_token".
• :user_url is set to "/user".
• :user_emails_url is set to "/user/emails".
• :authorization_params is set to [scope: "read:user,user:email"].
• :auth_method is set to :client_secret_post.

Schema:

• :name (t:atom/0) - Required. Uniquely identifies the strategy.

• :client_id - Required. The OAuth2 client ID.
  Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string.
  See the module documentation for AshAuthentication.Secret for more information.

  Example:

  client_id fn _, resource ->
    :my_app
    |> Application.get_env(resource, [])
    |> Keyword.fetch(:oauth_client_id)
  end
  

• :base_url - 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.
  See the module documentation for AshAuthentication.Secret for more information.

  Example:

  base_url fn _, resource ->
    :my_app
    |> Application.get_env(resource, [])
    |> Keyword.fetch(:oauth_site)
  end
  

• :site - Deprecated: Use base_url instead.

• :auth_method - The authentication strategy used, optional. If not set, no authentication will be used during the access token request. The value may be one of the following:

  • :client_secret_basic
  • :client_secret_post
  • :client_secret_jwt
  • :private_key_jwt Valid values are nil, :client_secret_basic, :client_secret_post, :client_secret_jwt, :private_key_jwt The default value is :client_secret_post.

• :client_secret - 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.
  See the module documentation for AshAuthentication.Secret for more information.

  Example:

  site fn _, resource ->
    :my_app
    |> Application.get_env(resource, [])
    |> Keyword.fetch(:oauth_site)
  end
  

• :authorize_url - Required. The API url to the OAuth2 authorize endpoint.
  Relative to the value of site.
  Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string.
  See the module documentation for AshAuthentication.Secret for more information.

  Example:

  authorize_url fn _, _ -> {:ok, "https://exampe.com/authorize"} end
  

• :token_url - Required. The API url to access the token endpoint.
  Relative to the value of site.
  Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string.
  See the module documentation for AshAuthentication.Secret for more information.

  Example:

  token_url fn _, _ -> {:ok, "https://example.com/oauth_token"} end
  

• :user_url - Required. The API url to access the user endpoint.
  Relative to the value of site.
  Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string.
  See the module documentation for AshAuthentication.Secret for more information.

  Example:

  user_url fn _, _ -> {:ok, "https://example.com/userinfo"} end
  

• :private_key - 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.
  See the module documentation for AshAuthentication.Secret for more information.

• :redirect_uri - Required. The callback URI base.
  Not the whole URI back to the callback endpoint, but the URI to your AuthPlug. We can generate the rest.
  Whilst not particularly secret, it seemed prudent to allow this to be configured dynamically so that you can use different URIs for different environments.
  Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string.
  See the module documentation for AshAuthentication.Secret for more information.

• :authorization_params (t:keyword/0) - Any additional parameters to encode in the request phase.
  eg: authorization_params scope: "openid profile email" The default value is [].

• :registration_enabled? (t:boolean/0) - Is registration enabled for this provider?
  If this option is enabled, then new users will be able to register for your site when authenticating and not already present.
  If not, then only existing users will be able to authenticate. The default value is true.

• :register_action_name (t:atom/0) - The name of the action to use to register a user.
  Only needed if registration_enabled? is true.
  Because we we don't know the response format of the server, you must implement your own registration action of the same name.
  See the "Registration and Sign-in" section of the module documentation for more information.
  The default is computed from the strategy name eg: register_with_#{name}.

• :sign_in_action_name (t:atom/0) - The name of the action to use to sign in an existing user.
  Only needed if registration_enabled? is false.
  Because we don't know the response format of the server, you must implement your own sign-in action of the same name.
  See the "Registration and Sign-in" section of the module documentation for more information.
  The default is computed from the strategy name, eg: sign_in_with_#{name}.

• :identity_resource - The resource used to store user identities.
  Given that a user can be signed into multiple different authentication providers at once we use the AshAuthentication.UserIdentity resource to build a mapping between users, providers and that provider's uid.
  See the Identities section of the module documentation for more information.
  Set to false to disable. The default value is false.

• :identity_relationship_name (t:atom/0) - Name of the relationship to the provider identities resource The default value is :identities.

• :identity_relationship_user_id_attribute (t:atom/0) - The name of the destination (user_id) attribute on your provider identity resource.
  The only reason to change this would be if you changed the user_id_attribute_name option of the provider identity. The default value is :user_id.

• :icon (t:atom/0) - The name of an icon to use in any potential UI.
  This is a hint for UI generators to use, and not in any way canonical. The default value is :oauth2.

authentication.strategies.github

github name \\ :github

Provides a pre-configured authentication strategy for GitHub.

This strategy is built using the :oauth2 strategy, and thus provides all the same configuration options should you need them.

For more information see the Github Quick Start Guide in our documentation.

Strategy defaults:

The following defaults are applied:

• :base_url is set to "https://api.github.com".
• :authorize_url is set to "https://github.com/login/oauth/authorize".
• :token_url is set to "https://github.com/login/oauth/access_token".
• :user_url is set to "/user".
• :user_emails_url is set to "/user/emails".
• :authorization_params is set to [scope: "read:user,user:email"].
• :auth_method is set to :client_secret_post.

Schema:

Arguments

Name	Type	Default	Docs
name{: #authentication-strategies-github-name .spark-required}	atom		Uniquely identifies the strategy.

Options

Name	Type	Default	Docs
client_id{: #authentication-strategies-github-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. See the module documentation for AshAuthentication.Secret for more information. Example: elixir client_id fn _, resource -> :my_app |> Application.get_env(resource, []) |> Keyword.fetch(:oauth_client_id) end
authorize_url{: #authentication-strategies-github-authorize_url .spark-required}	(any, any -> any) | module | String.t		The API url to the OAuth2 authorize endpoint. Relative to the value of site. Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string. See the module documentation for AshAuthentication.Secret for more information. Example: elixir authorize_url fn _, _ -> {:ok, "https://exampe.com/authorize"} end
token_url{: #authentication-strategies-github-token_url .spark-required}	(any, any -> any) | module | String.t		The API url to access the token endpoint. Relative to the value of site. Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string. See the module documentation for AshAuthentication.Secret for more information. Example: elixir token_url fn _, _ -> {:ok, "https://example.com/oauth_token"} end
user_url{: #authentication-strategies-github-user_url .spark-required}	(any, any -> any) | module | String.t		The API url to access the user endpoint. Relative to the value of site. Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string. See the module documentation for AshAuthentication.Secret for more information. Example: elixir user_url fn _, _ -> {:ok, "https://example.com/userinfo"} end
redirect_uri{: #authentication-strategies-github-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. We can generate the rest. Whilst not particularly secret, it seemed prudent to allow this to be configured dynamically so that you can use different URIs for different environments. Takes either a module which implements the AshAuthentication.Secret behaviour, a 2 arity anonymous function or a string. See the module documentation for AshAuthentication.Secret for more information.
base_url{: #authentication-strategies-github-base_url }	(any, any -> any) | module | String.t		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. See the module documentation for AshAuthentication.Secret for more information. Example: elixir base_url fn _, resource -> :my_app |> Application.get_env(resource, []) |> Keyword.fetch(:oauth_site) end
site{: #authentication-strategies-github-site }	(any, any -> any) | module | String.t		Deprecated: Use base_url instead.
auth_method{: #authentication-strategies-github-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. The value may be one of the following: * :client_secret_basic * :client_secret_post * :client_secret_jwt * :private_key_jwt
client_secret{: #authentication-strategies-github-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. See the module documentation for AshAuthentication.Secret for more information. Example: elixir site fn _, resource -> :my_app |> Application.get_env(resource, []) |> Keyword.fetch(:oauth_site) end
private_key{: #authentication-strategies-github-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. See the module documentation for AshAuthentication.Secret for more information.
authorization_params{: #authentication-strategies-github-authorization_params }	Keyword.t	[]	Any additional parameters to encode in the request phase. eg: authorization_params scope: "openid profile email"
registration_enabled?{: #authentication-strategies-github-registration_enabled? }	boolean	true	Is registration enabled for this provider? If this option is enabled, then new users will be able to register for your site when authenticating and not already present. If not, then only existing users will be able to authenticate.
register_action_name{: #authentication-strategies-github-register_action_name }	atom		The name of the action to use to register a user. Only needed if registration_enabled? is true. Because we we don't know the response format of the server, you must implement your own registration action of the same name. See the "Registration and Sign-in" section of the module documentation for more information. The default is computed from the strategy name eg: register_with_#{name}.
sign_in_action_name{: #authentication-strategies-github-sign_in_action_name }	atom		The name of the action to use to sign in an existing user. Only needed if registration_enabled? is false. Because we don't know the response format of the server, you must implement your own sign-in action of the same name. See the "Registration and Sign-in" section of the module documentation for more information. The default is computed from the strategy name, eg: sign_in_with_#{name}.
identity_resource{: #authentication-strategies-github-identity_resource }	module | false	false	The resource used to store user identities. Given that a user can be signed into multiple different authentication providers at once we use the AshAuthentication.UserIdentity resource to build a mapping between users, providers and that provider's uid. See the Identities section of the module documentation for more information. Set to false to disable.
identity_relationship_name{: #authentication-strategies-github-identity_relationship_name }	atom	:identities	Name of the relationship to the provider identities resource
identity_relationship_user_id_attribute{: #authentication-strategies-github-identity_relationship_user_id_attribute }	atom	:user_id	The name of the destination (user_id) attribute on your provider identity resource. The only reason to change this would be if you changed the user_id_attribute_name option of the provider identity.
icon{: #authentication-strategies-github-icon }	atom	:oauth2	The name of an icon to use in any potential UI. This is a hint for UI generators to use, and not in any way canonical.

Introspection

Target: AshAuthentication.Strategy.OAuth2