Code0::Identities

This gem can load and validate external identities

Supported platforms

OAuth:

• Google
• Discord
• Microsoft
• Github
• Gitlab
• OIDC / oAuth2
• SAML

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add code0-identities

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install code0-identities

Usage

You can use predefined Providers to load an identity from for example Discord:

require"code0/identities"beginidentity=Code0::Identities::Provider::Discord.new({redirect_uri: "http://localhost:8080/redirect",client_id: "id",client_secret: "xxxx"}).load_identity({code: "a_valid_code"})rescueCode0::Error=>eputs"Error occurred while loading the identity",eexit!end# Then you can use the details from the userputsidentity.provider# = :discordputsidentity.usernameputsidentity.identifier# ...

Or you can use a provider with multiple configured providers:

require"code0/identities"identity_provider=Code0::Identities::IdentityProvider.newidentity_provider.add_provider(:gitlab,my_gitlab_configuration)identity_provider.add_named_provider(:my_custom_gitlab_provider,:gitlab,my_custom_gitlab_provider_configuration)# Now you can either use the custom "my_custom_gitlab_provider" provider# or the "gitlab" provideridentity_provider.load_identity(:gitlab,params)# oridentity_provider.load_identity(:my_custom_gitlab_provider,params)

We also support passing in a function as a configuration instead of a hash

defget_identityprovider=Code0::Identities::Provider::Discord.new(->{fetch_configuration})provider.load_identity(params)enddeffetch_configuration# Do some database action, to dynamicly load the configuration{redirect_uri: "http://localhost:8080/redirect",client_id: "some dynamic value",client_secret: "xxxx"}end

Configuration

As you already know, we allow / require to pass in a configuration. Here are all avaiable configuration keys:

Oauth Based:

Here is the updated table where each key in the JSON (identifier, username, etc.) is explicitly labeled:

Name	Description	Default
client_id	The client id of the application (needs to be set)	(no default specified)
client_secret	The client secret of the application (needs to be set)	(no default specified)
redirect_uri	The redirect URL of the application (needs to be set)	(no default specified)
provider_name	The provider name (not necessarily)	depends on the provider (e.g., discord, github)
user_details_url	The user details URL to gather user information (only for OIDC)	(no default specified)
authorization_url	The URL which the user has to access to authorize (only for OIDC)	(no default specified)
attribute_statements	The keys which the response of the user details has (id, name, email, ...) (only for OIDC)	{} (see below for more)
attribute_statements.identifier	The identifier of the user to identify (only for OIDC)	["id", "sub", "identifier"]
attribute_statements.username	The username of the user (only for OIDC)	["username", "name", "login"]
attribute_statements.email	The email address of the user (only for OIDC)	["email", "mail"]
attribute_statements.firstname	The first name of the user (only for OIDC)	["first_name", "firstname", ...]
attribute_statements.lastname	The last name of the user (only for OIDC)	["last_name", "lastname", ...]

SAML

Name	Description	Default
provider_name	The provider name (not necessarily)	saml
attribute_statements	The keys which the response of the user details has (id, name, email, ...) (only for OIDC)	{} (see below for more)
attribute_statements.username	The username of the user	["username", "name", ...]
attribute_statements.email	The email address of the user	["email", "mail", ...]
attribute_statements.firstname	The first name of the user	["first_name", "firstname", ...]
attribute_statements.lastname	The last name of the user	["last_name", "lastname", ...]
settings	The settings to configure the saml response/requests (see SAML-Toolkits#L200)	{}
response_settings	The response settings to disable some checks if you want (see SAML-Toolkits#L234)	{}
metadata_url	The metadata url to fetch the metadatas (replacement for settings)	(no default specified)