Skip to content
masks

Providers (SSO)

Providers are a server-only feature that enable single sign-on. You add providers to your masks server, enable them on clients (or globally), and actors can rely on them to log in.

Adding providers

You can add clients manually as a manager, via the API, CLI, with seeds, a clients.yml file, or a number of other ways.

Command line

You can add and edit providers using the masks provider command`.

Terminal window
masks provider github client_id=...
masks provider github common=true # enable for all clients

Ruby API

You can also seed providers in Ruby with the Masks global:

provider = Masks.providers.new(key: "my-provider", type: "oidc", **opts)
provider.save

providers.yml

Any providers specified in providers.yml will be available to masks (in server mode only):

providers.yml
github:
  common: true
  client_id: <%= ENV['MASKS_GITHUB_CLIENT_ID'] %>
  client_secret: <%= ENV['MASKS_GITHUB_CLIENT_SECRET'] %>


my-provider:
  type: oidc
  ...

Settings

The following settings exist for all providers, regardless of type:

key string The providers's unique key.
default null
name string A name shown when during login to the provider.
default null
type string The provider type, which dictates overall functionality.
default null
common boolean Toggle availability for all clients.
default null
enabled boolean Enable or disable the provider without deleting it.
default null
assign_client string .
default null
remove_client string .
default null
created_at datetime The time the provider was created.
read-only
updated_at datetime The last time the provider was saved.
read-only
disabled_at datetime The time the provider was disabled.
read-only

You must specify a type when adding a provider. For example:

providers.yml
my-github-app:
  type: github
  ...

Custom types

You can add custom types for cases where masks built-ins don’t work.

providers.yml
my-provider:
  type: custom-provider
  ...
masks.yml
provider_types:
  custom-provider: MyApp::CustomProvider
class MyApp::CustomProvider < Masks::Providers::Abstract
  # See the Ruby API reference for more information
end

Built-in types

There are many built-in types with additional settings:

oidc settings

client_id string .
default null
client_secret string .
default null
scopes string .
default null

oauth settings

client_id string The shared client identifier.
default null
client_secret string The shared client secret.
default null
scopes string Requested scopes, space-separated.
default null

github settings

client_id string The shared client identifier.
default null
client_secret string The shared client secret.
default null
scopes string Requested scopes, space-separated.
default null

google settings

client_id string The shared client identifier.
default null
client_secret string The shared client secret.
default null
scopes string Requested scopes, space-separated.
default null

facebook settings

client_id string The shared client identifier.
default null
client_secret string The shared client secret.
default null
scopes string Requested scopes, space-separated.
default public_profile

twitter settings

client_id string The shared client identifier.
default null
client_secret string The shared client secret.
default null
scopes string Requested scopes, space-separated.
default tweet.read users.read

apple settings

pem string Contents of .p8 file from apple (including trailing newline).
default null
key_id string Key ID from Key details page.
default null
team_id string aka App ID prefix.
default null
scopes string Requested scopes, space-separated.
default email name
client_id string Service Identifier, from your Services Id config.
default null