Copyright | (c) 2015-2016 Brendan Hay |
---|---|
License | Mozilla Public License, v. 2.0. |
Maintainer | Brendan Hay <brendan.g.hay@gmail.com> |
Stability | provisional |
Portability | non-portable (GHC extensions) |
Safe Haskell | None |
Language | Haskell2010 |
Explicitly specify your Google credentials, or retrieve them from the underlying OS.
Synopsis
- data Credentials (s :: [Symbol])
- = FromMetadata !ServiceId
- | FromClient !OAuthClient !(OAuthCode s)
- | FromAccount !ServiceAccount
- | FromUser !AuthorizedUser
- getApplicationDefault :: (MonadIO m, MonadCatch m) => Manager -> m (Credentials s)
- fromWellKnownPath :: (MonadIO m, MonadCatch m) => m (Credentials s)
- fromFilePath :: (MonadIO m, MonadCatch m) => FilePath -> m (Credentials s)
- saveAuthorizedUserToWellKnownPath :: (MonadIO m, MonadCatch m) => Bool -> AuthorizedUser -> m ()
- saveAuthorizedUser :: (MonadIO m, MonadCatch m) => FilePath -> Bool -> AuthorizedUser -> m ()
- serviceAccountUser :: forall s. AllowScopes s => Maybe Text -> Credentials s -> Credentials s
- installedApplication :: OAuthClient -> OAuthCode s -> Credentials s
- formURL :: AllowScopes (s :: [Symbol]) => OAuthClient -> proxy s -> Text
- authorize :: (MonadIO m, MonadCatch m, AllowScopes s) => Request -> Store s -> Logger -> Manager -> m Request
- data Store (s :: [Symbol])
- initStore :: (MonadIO m, MonadCatch m, AllowScopes s) => Credentials s -> Logger -> Manager -> m (Store s)
- retrieveAuthFromStore :: (MonadIO m, MonadCatch m, AllowScopes s) => Store s -> m (Auth s)
- data Auth (s :: [Symbol]) = Auth {
- _credentials :: !(Credentials s)
- _token :: !(OAuthToken s)
- authToAuthorizedUser :: AllowScopes s => Auth s -> Either Text AuthorizedUser
- exchange :: forall m s. (MonadIO m, MonadCatch m, AllowScopes s) => Credentials s -> Logger -> Manager -> m (Auth s)
- refresh :: forall m s. (MonadIO m, MonadCatch m, AllowScopes s) => Auth s -> Logger -> Manager -> m (Auth s)
- checkGCEVar :: String
- cloudSDKConfigDir :: String
- defaultCredentialsFile :: String
- class AsAuthError a where
- _AuthError :: Prism' a AuthError
- _RetrievalError :: Prism' a HttpException
- _MissingFileError :: Prism' a FilePath
- _InvalidFileError :: Prism' a (FilePath, Text)
- _TokenRefreshError :: Prism' a (Status, Text, Maybe Text)
- data AuthError
- data OAuthClient = OAuthClient {
- _clientId :: !ClientId
- _clientSecret :: !GSecret
- data OAuthToken (s :: [Symbol]) = OAuthToken {
- _tokenAccess :: !AccessToken
- _tokenRefresh :: !(Maybe RefreshToken)
- _tokenExpiry :: !UTCTime
- newtype OAuthCode (s :: [Symbol]) = OAuthCode Text
- newtype OAuthScope = OAuthScope Text
- newtype AccessToken = AccessToken Text
- newtype RefreshToken = RefreshToken Text
- newtype GSecret = GSecret Text
- newtype ServiceId = ServiceId Text
- newtype ClientId = ClientId Text
- module Network.Google.Auth.Scope
Credentials
data Credentials (s :: [Symbol]) Source #
The supported credential mechanisms.
FromMetadata !ServiceId | Obtain and refresh access tokens from the underlying GCE host metadata
at |
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 A |
FromUser !AuthorizedUser | Use the specified An |
Instances
AllowScopes s => AllowScopes (Credentials s :: Type) Source # | |
Defined in Network.Google.Auth.Scope allowScopes :: proxy (Credentials s) -> [OAuthScope] Source # |
Application Default Credentials
getApplicationDefault :: (MonadIO m, MonadCatch m) => Manager -> m (Credentials s) Source #
Performs credentials discovery in the following order:
- Read the default credentials from a file specified by
the environment variable
GOOGLE_APPLICATION_CREDENTIALS
if it exists. - 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 variableCLOUDSDK_CONFIG
if it exists. - 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 as1
ortrue
.
The specified Scope
s 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
.
fromWellKnownPath :: (MonadIO m, MonadCatch m) => m (Credentials s) Source #
Attempt to load either a service_account
or authorized_user
formatted
file to obtain the credentials neccessary to perform a token refresh.
The specified Scope
s 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
.
fromFilePath :: (MonadIO m, MonadCatch m) => FilePath -> m (Credentials s) Source #
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 Scope
s 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
.
saveAuthorizedUserToWellKnownPath Source #
:: (MonadIO m, MonadCatch m) | |
=> Bool | Force to save if True |
-> AuthorizedUser | |
-> m () |
Save AuthorizedUser
See: cloudSDKConfigPath
, defaultCredentialsPath
.
:: (MonadIO m, MonadCatch m) | |
=> FilePath | |
-> Bool | Force to save if True |
-> AuthorizedUser | |
-> m () |
Save AuthorizedUser
Service account user impersonation
serviceAccountUser :: forall s. AllowScopes s => Maybe Text -> Credentials s -> Credentials s Source #
Set the user to be impersonated for a service account with domain wide delegation. See https://developers.google.com/identity/protocols/OAuth2ServiceAccount
Installed Application Credentials
installedApplication :: OAuthClient -> OAuthCode s -> Credentials s Source #
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 Data.Text as T import Data.Text.IO as T import System.Exit (exitFailure) import System.Info (os) import System.Process (rawSystem)
redirectPrompt :: AllowScopes (s :: [Symbol]) => OAuthClient -> proxy s -> IO (OAuthCode s) redirectPrompt c p = do let url = formURL c p T.putStrLn $ "Opening URL " `T.append` url _ <- case os of "darwin" -> rawSystem "open" [unpack url] "linux" -> rawSystem "xdg-open" [unpack url] _ -> T.putStrLn "Unsupported OS" >> exitFailure T.putStrLn "Please input the authorisation code: " OAuthCode <$> T.getLine
This ensures the scopes passed to formURL
and the type of OAuthCode
s
are correct.
formURL :: AllowScopes (s :: [Symbol]) => OAuthClient -> proxy s -> Text Source #
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 Source #
Apply the (by way of possible token refresh) a bearer token to the authentication header of a request.
Thread-safe Storage
initStore :: (MonadIO m, MonadCatch m, AllowScopes s) => Credentials s -> Logger -> Manager -> m (Store s) Source #
Construct storage containing the credentials which have not yet been exchanged or refreshed.
retrieveAuthFromStore :: (MonadIO m, MonadCatch m, AllowScopes s) => Store s -> m (Auth s) Source #
Retrieve auth from storage
data Auth (s :: [Symbol]) Source #
An OAuthToken
that can potentially be expired, with the original
credentials that can be used to perform a refresh.
Auth | |
|
authToAuthorizedUser :: AllowScopes s => Auth s -> Either Text AuthorizedUser Source #
authToAuthorizedUser
converts Auth
into an AuthorizedUser
by returning Right
if there is a FromClient
-constructed
Credentials and a refreshed token; otherwise, returning
Left
with error message.
exchange :: forall m s. (MonadIO m, MonadCatch m, AllowScopes s) => Credentials s -> Logger -> Manager -> m (Auth s) Source #
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) Source #
Refresh an existing OAuthToken
.
Default Constants
checkGCEVar :: String Source #
The NO_GCE_CHECK
environment variable.
cloudSDKConfigDir :: String Source #
The environment variable name which is used to specify the directory
containing the application_default_credentials.json
generated by gcloud init
.
defaultCredentialsFile :: String Source #
The environment variable pointing the file with local Application Default Credentials.
Handling Errors
class AsAuthError a where Source #
_AuthError :: Prism' a AuthError Source #
A general authentication error.
_RetrievalError :: Prism' a HttpException Source #
An error occured while communicating over HTTP with either then local metadata or remote accounts.google.com endpoints.
_MissingFileError :: Prism' a FilePath Source #
The specified default credentials file could not be found.
_InvalidFileError :: Prism' a (FilePath, Text) Source #
An error occured parsing the default credentials file.
_TokenRefreshError :: Prism' a (Status, Text, Maybe Text) Source #
An error occured when attempting to refresh a token.
Instances
An error thrown when attempting to readwrite AuthNAuthZ information.
RetrievalError HttpException | |
MissingFileError FilePath | |
InvalidFileError FilePath Text | |
TokenRefreshError Status Text (Maybe Text) | |
FileExistError FilePath |
Instances
Show AuthError Source # | |
Exception AuthError Source # | |
Defined in Network.Google.Internal.Auth toException :: AuthError -> SomeException # fromException :: SomeException -> Maybe AuthError # displayException :: AuthError -> String # | |
AsAuthError AuthError Source # | |
Defined in Network.Google.Internal.Auth |
OAuth Types
data OAuthClient Source #
A client identifier and accompanying secret used to obtain/refresh a token.
OAuthClient | |
|
Instances
Eq OAuthClient Source # | |
Defined in Network.Google.Internal.Auth (==) :: OAuthClient -> OAuthClient -> Bool # (/=) :: OAuthClient -> OAuthClient -> Bool # | |
Show OAuthClient Source # | |
Defined in Network.Google.Internal.Auth showsPrec :: Int -> OAuthClient -> ShowS # show :: OAuthClient -> String # showList :: [OAuthClient] -> ShowS # |
data OAuthToken (s :: [Symbol]) Source #
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.
OAuthToken | |
|
Instances
Eq (OAuthToken s) Source # | |
Defined in Network.Google.Internal.Auth (==) :: OAuthToken s -> OAuthToken s -> Bool # (/=) :: OAuthToken s -> OAuthToken s -> Bool # | |
Show (OAuthToken s) Source # | |
Defined in Network.Google.Internal.Auth showsPrec :: Int -> OAuthToken s -> ShowS # show :: OAuthToken s -> String # showList :: [OAuthToken s] -> ShowS # | |
FromJSON (UTCTime -> OAuthToken s) Source # | |
Defined in Network.Google.Internal.Auth parseJSON :: Value -> Parser (UTCTime -> OAuthToken s) # parseJSONList :: Value -> Parser [UTCTime -> OAuthToken s] # |
newtype OAuthCode (s :: [Symbol]) Source #
An OAuth client authorization code.
Instances
Eq (OAuthCode s) Source # | |
Ord (OAuthCode s) Source # | |
Defined in Network.Google.Internal.Auth | |
Read (OAuthCode s) Source # | |
Show (OAuthCode s) Source # | |
IsString (OAuthCode s) Source # | |
Defined in Network.Google.Internal.Auth fromString :: String -> OAuthCode s # | |
Generic (OAuthCode s) Source # | |
ToJSON (OAuthCode s) Source # | |
Defined in Network.Google.Internal.Auth | |
FromJSON (OAuthCode s) Source # | |
ToHttpApiData (OAuthCode s) Source # | |
Defined in Network.Google.Internal.Auth toUrlPiece :: OAuthCode s -> Text # toEncodedUrlPiece :: OAuthCode s -> Builder # toHeader :: OAuthCode s -> ByteString # toQueryParam :: OAuthCode s -> Text # | |
type Rep (OAuthCode s) Source # | |
Defined in Network.Google.Internal.Auth |
newtype OAuthScope #
An OAuth2 scope.
Instances
Re-exported Types
newtype AccessToken #
An OAuth2 access token.
Instances
newtype RefreshToken #
An OAuth2 refresh token.
Instances
An opaque client secret.
Instances
Eq GSecret | |
Ord GSecret | |
Read GSecret | |
Show GSecret | |
IsString GSecret | |
Defined in Network.Google.Types fromString :: String -> GSecret # | |
Generic GSecret | |
ToJSON GSecret | |
Defined in Network.Google.Types | |
FromJSON GSecret | |
FromHttpApiData GSecret | |
Defined in Network.Google.Types parseUrlPiece :: Text -> Either Text GSecret # parseHeader :: ByteString -> Either Text GSecret # | |
ToHttpApiData GSecret | |
Defined in Network.Google.Types toUrlPiece :: GSecret -> Text # toEncodedUrlPiece :: GSecret -> Builder # toHeader :: GSecret -> ByteString # toQueryParam :: GSecret -> Text # | |
type Rep GSecret | |
Defined in Network.Google.Types |
A service identifier.
Instances
Eq ServiceId | |
Ord ServiceId | |
Defined in Network.Google.Types | |
Read ServiceId | |
Show ServiceId | |
IsString ServiceId | |
Defined in Network.Google.Types fromString :: String -> ServiceId # | |
Generic ServiceId | |
ToJSON ServiceId | |
Defined in Network.Google.Types | |
FromJSON ServiceId | |
FromHttpApiData ServiceId | |
Defined in Network.Google.Types parseUrlPiece :: Text -> Either Text ServiceId # parseHeader :: ByteString -> Either Text ServiceId # | |
ToHttpApiData ServiceId | |
Defined in Network.Google.Types toUrlPiece :: ServiceId -> Text # toEncodedUrlPiece :: ServiceId -> Builder # toHeader :: ServiceId -> ByteString # toQueryParam :: ServiceId -> Text # | |
type Rep ServiceId | |
Defined in Network.Google.Types |
A client identifier.
Instances
Eq ClientId | |
Ord ClientId | |
Defined in Network.Google.Types | |
Read ClientId | |
Show ClientId | |
IsString ClientId | |
Defined in Network.Google.Types fromString :: String -> ClientId # | |
Generic ClientId | |
ToJSON ClientId | |
Defined in Network.Google.Types | |
FromJSON ClientId | |
FromHttpApiData ClientId | |
Defined in Network.Google.Types parseUrlPiece :: Text -> Either Text ClientId # parseHeader :: ByteString -> Either Text ClientId # | |
ToHttpApiData ClientId | |
Defined in Network.Google.Types toUrlPiece :: ClientId -> Text # toEncodedUrlPiece :: ClientId -> Builder # toHeader :: ClientId -> ByteString # toQueryParam :: ClientId -> Text # | |
type Rep ClientId | |
Defined in Network.Google.Types |
Re-exported Modules
module Network.Google.Auth.Scope