Ptolemy v0.2.0 Ptolemy.Auth behaviour View Source

Ptolemy.Auth provides authentication implementations to a remote vault server.

Usage

All token request should call the Ptolemy.Auth.authenticate/4 function and not the authenticate/3 callback found in each modules implementing this behaviour!

Here are a few examples of the usage:

#Approle, no IAP
Ptolemy.Auth.authenticate(:Approle, "https://test-vault.com", %{secret_id: "test", role_id; "test"}, [])

#Approle with IAP
Ptolemy.Auth.authenticate(:Approle, "https://test-vault.com", %{secret_id: "test", role_id; "test"}, [iap_svc_acc:  @gcp_svc1_with_vault_perm, client_id: @fake_id, exp: 2000])

#Approle with IAP and `bearer` token being re-used
Ptolemy.Auth.authenticate(:Approle, "https://test-vault.com", %{secret_id: "test", role_id: "test"}, {"Authorization", "Bearer 98a4c7ab98a4c7ab98a4c7ab"})

#GCP with no IAP
Ptolemy.Auth.authenticate(:GCP, "https://test-vault.com", my_svc, [])

#GCP with IAP, 2 Google service accounts, one for vault one for IAP
Ptolemy.Auth.authenticate(:GCP, @vurl, %{gcp_svc_acc: @gcp_svc1_with_vault_perm, vault_role: "test", exp: 3000}, [iap_svc_acc:  my_svc, client_id: @fake_id, exp: 2000])

#GCP with IAP, re-using the same GCP service account being used to authenticate to vault inorder to auth into IAP
Ptolemy.Auth.authenticate(:GCP, @vurl, %{gcp_svc_acc: @gcp_svc1_with_vault_perm, vault_role: "test", exp: 3000}, [iap_svc_acc:  :reuse, client_id: @fake_id, exp: 2000])

#GCP with IAP and `bearer` token being re-used
Ptolemy.Auth.authenticate(:GCP, @vurl, %{gcp_svc_acc: @gcp_svc1_with_vault_perm, vault_role: "test", exp: 3000}, {"Authorization", "Bearer 98a4c7ab98a4c7ab98a4c7ab"})

Link to this section Summary

Types

Atoms representing the authentication methods that is currently supported on ptolemy

Credential data needed to authenticated to a remote vault server

Google Identity Aware Proxy authentication data

Authentication options, used to specify IAP credentials and other future authentication options

List representing an IAP token

Vault authentication data

Functions

Authenticates against a remote vault server with specified auth strategy and options

Sends a payload to a remote vault server's authentication endpoint

Creates a %Tesla.Client{} pointing to a remote vault server

Callbacks

Authentication method specific callback to be implemented by different modules

Link to this section Types

Link to this type

auth_method() View Source
auth_method() :: :GCP | :Approle

Atoms representing the authentication methods that is currently supported on ptolemy.

Currently supported methods are:

  • GCP -> :GCP
  • Approle -> :Approle
Link to this type

cred_data() View Source
cred_data() ::
  %{gcp_svc_acc: map(), vault_role: String.t(), exp: pos_integer()}
  | %{secret_id: String.t(), role_id: String.t()}

Credential data needed to authenticated to a remote vault server.

Each specific auth method's credential data have a different schema.

Link to this type

iap_auth_data() View Source
iap_auth_data() :: %{token: {String.t(), String.t()}}

Google Identity Aware Proxy authentication data.

Link to this type

iap_auth_opts() View Source
iap_auth_opts() ::
  []
  | [iap_svc_acc: map(), client_id: String.t(), exp: pos_integer()]
  | [iap_svc_acc: :reuse, client_id: String.t(), exp: pos_integer()]
  | {String.t(), String.t()}

Authentication options, used to specify IAP credentials and other future authentication options.

If under the :iap_svc_acc key :reuse is specified and the auth method was set to :GCP, Ptolemy.Auth will attempt to re-use the GCP service account specified under the supplied cred_data type.

:client_id is the OAuth2 client id, this can be found in Security -> Identity-Aware-Proxy -> Select the IAP resource -> Edit OAuth client.

:exp is the validity period for the token in seconds, google's API specifies that a token can only be valid for up to 3600 seconds.

Specifying a tuple of type {"Authorization", "Bearer ....."} will notify Ptolemy.Auth.authenticate/4 to reuse the token to prevent exessive auhtnetication calls to IAP.

Link to this type

iap_tok() View Source
iap_tok() :: [] | [{String.t(), String.t()}]

List representing an IAP token.

The token type returned from a sucessfull IAP call will always be of type Authorization Bearer.

Link to this type

vault_auth_data() View Source
vault_auth_data() :: %{
  token: {String.t(), String.t()},
  renewable: boolean(),
  lease_duration: pos_integer()
}

Vault authentication data.

Link to this section Functions

Link to this function

authenticate(method, url, credentials, opts) View Source
authenticate(auth_method(), String.t(), cred_data(), iap_auth_opts()) ::
  vault_auth_data()
  | %{vault: vault_auth_data(), iap: iap_auth_data()}
  | {:error, String.t()}

Authenticates against a remote vault server with specified auth strategy and options.

Currently the only supported options deals with IAP.

Note Specifying an empty list or a tuple to this function under iap_auth_opts will NOT return an IAP token and IAP credentials metadata.

Link to this function

login(client, auth_endp, payload) View Source
login(
  %Tesla.Client{adapter: term(), fun: term(), post: term(), pre: term()},
  String.t(),
  map()
) :: vault_auth_data() | {:error, String.t()}

Sends a payload to a remote vault server's authentication endpoint.

Link to this function

vault_auth_client(url, iap_tok) View Source
vault_auth_client(String.t(), iap_auth_opts()) :: %Tesla.Client{
  adapter: term(),
  fun: term(),
  post: term(),
  pre: term()
}

Creates a %Tesla.Client{} pointing to a remote vault server.

Link to this section Callbacks

Link to this callback

authenticate(endpoint, cred_data, iap_tok) View Source
authenticate(endpoint :: String.t(), cred_data(), iap_tok()) ::
  vault_auth_data() | {:error, String.t()}

Authentication method specific callback to be implemented by different modules.

Each modules representing a specific authentication method should implement this callback in its own module.