Network.Google.Auth

Explicitly specify your Google credentials, or retrieve them from the underlying OS.

Credentials

data Credentials s

The supported credential mechanisms.

Constructors

FromMetadata !ServiceId

Obtain and refresh access tokens from the underlying GCE host metadata at http://169.254.169.254.

FromClient !OAuthClient !(OAuthCode s)

Obtain and refresh access tokens using the specified client secret and authorization code obtained from.

See the OAuth2 Installed Application documentation for more information.

FromAccount !ServiceAccount

Use the specified service_account and scopes to sign and request an access token. The ServiceAccount will also be used for subsequent token refreshes.

A ServiceAccount is typically generated through the Google Developer Console.

FromUser !AuthorizedUser

Use the specified authorized_user to obtain and refresh access tokens.

An AuthorizedUser is typically created by the gcloud init command of the Google CloudSDK Tools.

Instances

AllowScopes [Symbol] s => AllowScopes * (Credentials s)

Application Default Credentials

getApplicationDefault :: (MonadIO m, MonadCatch m) => Manager -> m (Credentials s)

Performs credentials discovery in the following order:

1. Read the default credentials from a file specified by the environment variable GOOGLE_APPLICATION_CREDENTIALS if it exists.
2. Read the platform equivalent of ~/.config/gcloud/application_default_credentials.json if it exists. The ~/.config component of the path can be overriden by the environment variable CLOUDSDK_CONFIG if it exists.
3. Retrieve the default service account application credentials if running on GCE. The environment variable NO_GCE_CHECK can be used to skip this check if set to a truthy value such as 1 or true.

The specified Scopes are used to authorize any service_account that is found with the appropriate OAuth2 scopes, otherwise they are not used. See the top-level module of each individual gogol-* library for a list of available scopes, such as Network.Google.Compute.computeScope.

See: Application Default Credentials

fromWellKnownPath :: (MonadIO m, MonadCatch m) => m (Credentials s)

Attempt to load either a service_account or authorized_user formatted file to obtain the credentials neccessary to perform a token refresh.

The specified Scopes are used to authorize any service_account that is found with the appropriate scopes, otherwise they are not used. See the top-level module of each individual gogol-* library for a list of available scopes, such as Network.Google.Compute.computeScope.

See: cloudSDKConfigPath, defaultCredentialsPath.

fromFilePath :: (MonadIO m, MonadCatch m) => FilePath -> m (Credentials s)

Attempt to load either a service_account or authorized_user formatted file to obtain the credentials neccessary to perform a token refresh from the specified file.

The specified Scopes are used to authorize any service_account that is found with the appropriate scopes, otherwise they are not used. See the top-level module of each individual gogol-* library for a list of available scopes, such as Network.Google.Compute.computeScope.

Installed Application Credentials

installedApplication :: OAuthClient -> OAuthCode s -> Credentials s

Create new Installed Application credentials.

Since it is intended that the user opens the URL generated by formURL in a browser and the resulting OAuthCode is then received out-of-band, you must ensure that the scopes passed to formURL and the type of OAuthCode correctly match, otherwise an authorization error will occur.

For example, doing this via getLine and copy-paste:

{-# LANGUAGE ScopedTypeVariables #-}

import Data.Proxy     (Proxy (..))
import System.Exit    (exitFailure)
import System.Info    (os)
import System.Process (rawSystem)

import qualified Data.ByteString            as BS
import qualified Data.ByteString.Lazy.Char8 as LBS8

redirectPrompt :: forall s. OAuthClient -> proxy s -> IO (OAuthCode s)
redirectPrompt c p = do
    let url = LBS8.unpack (formURL c (Proxy :: Proxy s))
    putStrLn $ "Opening URL " ++ url
    case os of
        "darwin" -> rawSystem "open"     [url]
        "linux"  -> rawSystem "xdg-open" [url]
        _        -> putStrLn "Unsupported OS" >> exitFailure
    putStrLn "Please input the authorisation code: "
    OAuthCode . LBS.fromStrict <$> BS.getLine

This ensures the scopes passed to formURL and the type of OAuthCode s are correct.

formURL :: AllowScopes s => OAuthClient -> proxy s -> Text

Given an OAuthClient and a list of scopes to authorize, construct a URL that can be used to obtain the OAuthCode.

See: Forming the URL.

Authorizing Requests

authorize :: (MonadIO m, MonadCatch m, AllowScopes s) => Request -> Store s -> Logger -> Manager -> m Request

Apply the (by way of possible token refresh) a bearer token to the authentication header of a request.

Thread-safe Storage

data Store s

Data store which ensures thread-safe access of credentials.

initStore :: (MonadIO m, MonadCatch m, AllowScopes s) => Credentials s -> Logger -> Manager -> m (Store s)

Construct storage containing the credentials which have not yet been exchanged or refreshed.

data Auth s

An OAuthToken that can potentially be expired, with the original credentials that can be used to perform a refresh.

Constructors

Auth

Fields

_credentials :: !(Credentials s)

_token :: !(OAuthToken s)

exchange :: forall m s. (MonadIO m, MonadCatch m, AllowScopes s) => Credentials s -> Logger -> Manager -> m (Auth s)

Perform the initial credentials exchange to obtain a valid OAuthToken suitable for authorizing requests.

refresh :: forall m s. (MonadIO m, MonadCatch m, AllowScopes s) => Auth s -> Logger -> Manager -> m (Auth s)

Refresh an existing OAuthToken using

Default Constants

checkGCEVar :: String

The NO_GCE_CHECK environment variable.

cloudSDKConfigDir :: String

The environment variable name which is used to specify the directory containing the application_default_credentials.json generated by gcloud init.

defaultCredentialsFile :: String

The environment variable pointing the file with local Application Default Credentials.

Handling Errors

class AsAuthError a where

Minimal complete definition

_AuthError

Methods

_AuthError :: Prism' a AuthError

A general authentication error.

_RetrievalError :: Prism' a HttpException

An error occured while communicating over HTTP with either then local metadata or remote accounts.google.com endpoints.

_MissingFileError :: Prism' a FilePath

The specified default credentials file could not be found.

_InvalidFileError :: Prism' a (FilePath, Text)

An error occured parsing the default credentials file.

_TokenRefreshError :: Prism' a (Status, Text, Maybe Text)

An error occured when attempting to refresh a token.

Instances

AsAuthError SomeException

AsAuthError AuthError

data AuthError

An error thrown when attempting to read AuthN/AuthZ information.

Constructors

RetrievalError HttpException

MissingFileError FilePath

InvalidFileError FilePath Text

TokenRefreshError Status Text (Maybe Text)

Instances

Show AuthError

Exception AuthError

AsAuthError AuthError

OAuth Types

data OAuthClient

A client identifier and accompanying secret used to obtain/refresh a token.

Constructors

OAuthClient

Fields

_clientId :: !ClientId

_clientSecret :: !Secret

Instances

Eq OAuthClient

Show OAuthClient

data OAuthToken s

An OAuth bearer type token of the following form:

{
  \"token_type\": \"Bearer\",
  \"access_token\": \"eyJhbGci...\",
  \"refresh_token\": \"1/B3gq9K...\",
  \"expires_in\": 3600,
  ...
}

The _tokenAccess field will be inserted verbatim into the Authorization: Bearer ... header for all HTTP requests.

Constructors

OAuthToken

Fields

_tokenAccess :: !AccessToken

_tokenRefresh :: !(Maybe RefreshToken)

_tokenExpiry :: !UTCTime

Instances

Eq (OAuthToken s)

Show (OAuthToken s)

FromJSON (UTCTime -> OAuthToken s)

newtype OAuthCode s

An OAuth client authorization code.

Constructors

OAuthCode Text

Instances

Eq (OAuthCode s)

Ord (OAuthCode s)

Read (OAuthCode s)

Show (OAuthCode s)

IsString (OAuthCode s)

Generic (OAuthCode s)

ToJSON (OAuthCode s)

FromJSON (OAuthCode s)

ToHttpApiData (OAuthCode s)

type Rep (OAuthCode s)

newtype OAuthScope :: *

Constructors

OAuthScope Text

Instances

Eq OAuthScope

Ord OAuthScope

Read OAuthScope

Show OAuthScope

IsString OAuthScope

Generic OAuthScope

ToJSON OAuthScope

FromJSON OAuthScope

ToHttpApiData OAuthScope

FromHttpApiData OAuthScope

type Rep OAuthScope = D1 D1OAuthScope (C1 C1_0OAuthScope (S1 NoSelector (Rec0 Text)))

Re-exported Types

newtype AccessToken :: *

Constructors

AccessToken Text

Instances

Eq AccessToken

Ord AccessToken

Read AccessToken

Show AccessToken

IsString AccessToken

Generic AccessToken

ToJSON AccessToken

FromJSON AccessToken

ToHttpApiData AccessToken

FromHttpApiData AccessToken

type Rep AccessToken = D1 D1AccessToken (C1 C1_0AccessToken (S1 NoSelector (Rec0 Text)))

newtype RefreshToken :: *

Constructors

RefreshToken Text

Instances

Eq RefreshToken

Ord RefreshToken

Read RefreshToken

Show RefreshToken

IsString RefreshToken

Generic RefreshToken

ToJSON RefreshToken

FromJSON RefreshToken

ToHttpApiData RefreshToken

FromHttpApiData RefreshToken

type Rep RefreshToken = D1 D1RefreshToken (C1 C1_0RefreshToken (S1 NoSelector (Rec0 Text)))

newtype Secret :: *

Constructors

Secret Text

Instances

Eq Secret

Ord Secret

Read Secret

Show Secret

IsString Secret

Generic Secret

ToJSON Secret

FromJSON Secret

ToHttpApiData Secret

FromHttpApiData Secret

type Rep Secret = D1 D1Secret (C1 C1_0Secret (S1 NoSelector (Rec0 Text)))

newtype ServiceId :: *

Constructors

ServiceId Text

Instances

Eq ServiceId

Ord ServiceId

Read ServiceId

Show ServiceId

IsString ServiceId

Generic ServiceId

ToJSON ServiceId

FromJSON ServiceId

ToHttpApiData ServiceId

FromHttpApiData ServiceId

type Rep ServiceId = D1 D1ServiceId (C1 C1_0ServiceId (S1 NoSelector (Rec0 Text)))

newtype ClientId :: *

Constructors

ClientId Text

Instances

Eq ClientId

Ord ClientId

Read ClientId

Show ClientId

IsString ClientId

Generic ClientId

ToJSON ClientId

FromJSON ClientId

ToHttpApiData ClientId

FromHttpApiData ClientId

type Rep ClientId = D1 D1ClientId (C1 C1_0ClientId (S1 NoSelector (Rec0 Text)))

Re-exported Modules

module Network.Google.Auth.Scope