{-# LANGUAGE DataKinds #-} {-# LANGUAGE DeriveGeneric #-} {-# LANGUAGE FlexibleInstances #-} {-# LANGUAGE GeneralizedNewtypeDeriving #-} {-# LANGUAGE LambdaCase #-} {-# LANGUAGE NoImplicitPrelude #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE RecordWildCards #-} {-# LANGUAGE TypeFamilies #-} {-# OPTIONS_GHC -fno-warn-unused-imports #-} -- Module : Network.AWS.STS.AssumeRole -- Copyright : (c) 2013-2014 Brendan Hay <brendan.g.hay@gmail.com> -- License : This Source Code Form is subject to the terms of -- the Mozilla Public License, v. 2.0. -- A copy of the MPL can be found in the LICENSE file or -- you can obtain it at http://mozilla.org/MPL/2.0/. -- Maintainer : Brendan Hay <brendan.g.hay@gmail.com> -- Stability : experimental -- Portability : non-portable (GHC extensions) -- | Returns a set of temporary security credentials (consisting of an access -- key ID, a secret access key, and a security token) that you can use to -- access AWS resources that you might not normally have access to. Typically, -- you use AssumeRole for cross-account access or federation. Important: You -- cannot call AssumeRole by using AWS account credentials; access will be -- denied. You must use IAM user credentials or temporary security credentials -- to call AssumeRole. For cross-account access, imagine that you own multiple -- accounts and need to access resources in each account. You could create -- long-term credentials in each account to access those resources. However, -- managing all those credentials and remembering which one can access which -- account can be time consuming. Instead, you can create one set of long-term -- credentials in one account and then use temporary security credentials to -- access all the other accounts by assuming roles in those accounts. For more -- information about roles, see Roles in Using IAM. For federation, you can, -- for example, grant single sign-on access to the AWS Management Console. If -- you already have an identity and authentication system in your corporate -- network, you don't have to recreate user identities in AWS in order to -- grant those user identities access to AWS. Instead, after a user has been -- authenticated, you call AssumeRole (and specify the role with the -- appropriate permissions) to get temporary security credentials for that -- user. With those temporary security credentials, you construct a sign-in -- URL that users can use to access the console. For more information, see -- Scenarios for Granting Temporary Access in Using Temporary Security -- Credentials. The temporary security credentials are valid for the duration -- that you specified when calling AssumeRole, which can be from 900 seconds -- (15 minutes) to 3600 seconds (1 hour). The default is 1 hour. Optionally, -- you can pass an IAM access policy to this operation. If you choose not to -- pass a policy, the temporary security credentials that are returned by the -- operation have the permissions that are defined in the access policy of the -- role that is being assumed. If you pass a policy to this operation, the -- temporary security credentials that are returned by the operation have the -- permissions that are allowed by both the access policy of the role that is -- being assumed, and the policy that you pass. This gives you a way to -- further restrict the permissions for the resulting temporary security -- credentials. You cannot use the passed policy to grant permissions that are -- in excess of those allowed by the access policy of the role that is being -- assumed. For more information, see Permissions for AssumeRole in Using -- Temporary Security Credentials. To assume a role, your AWS account must be -- trusted by the role. The trust relationship is defined in the role's trust -- policy when the role is created. You must also have a policy that allows -- you to call sts:AssumeRole. Using MFA with AssumeRole You can optionally -- include multi-factor authentication (MFA) information when you call -- AssumeRole. This is useful for cross-account scenarios in which you want to -- make sure that the user who is assuming the role has been authenticated -- using an AWS MFA device. In that scenario, the trust policy of the role -- being assumed includes a condition that tests for MFA authentication; if -- the caller does not include valid MFA information, the request to assume -- the role is denied. The condition in a trust policy that tests for MFA -- authentication might look like the following example. "Condition": {"Null": -- {"aws:MultiFactorAuthAge": false}} For more information, see Configuring -- MFA-Protected API Access in the Using IAM guide. To use MFA with -- AssumeRole, you pass values for the SerialNumber and TokenCode parameters. -- The SerialNumber value identifies the user's hardware or virtual MFA -- device. The TokenCode is the time-based one-time password (TOTP) that the -- MFA devices produces. -- -- <http://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html> module Network.AWS.STS.AssumeRole ( -- * Request AssumeRole -- ** Request constructor , assumeRole -- ** Request lenses , arDurationSeconds , arExternalId , arPolicy , arRoleArn , arRoleSessionName , arSerialNumber , arTokenCode -- * Response , AssumeRoleResponse -- ** Response constructor , assumeRoleResponse -- ** Response lenses , arrAssumedRoleUser , arrCredentials , arrPackedPolicySize ) where import Network.AWS.Prelude import Network.AWS.Request.Query import Network.AWS.STS.Types import qualified GHC.Exts data AssumeRole = AssumeRole { _arDurationSeconds :: Maybe Nat , _arExternalId :: Maybe Text , _arPolicy :: Maybe Text , _arRoleArn :: Text , _arRoleSessionName :: Text , _arSerialNumber :: Maybe Text , _arTokenCode :: Maybe Text } deriving (Eq, Ord, Show) -- | 'AssumeRole' constructor. -- -- The fields accessible through corresponding lenses are: -- -- * 'arDurationSeconds' @::@ 'Maybe' 'Natural' -- -- * 'arExternalId' @::@ 'Maybe' 'Text' -- -- * 'arPolicy' @::@ 'Maybe' 'Text' -- -- * 'arRoleArn' @::@ 'Text' -- -- * 'arRoleSessionName' @::@ 'Text' -- -- * 'arSerialNumber' @::@ 'Maybe' 'Text' -- -- * 'arTokenCode' @::@ 'Maybe' 'Text' -- assumeRole :: Text -- ^ 'arRoleArn' -> Text -- ^ 'arRoleSessionName' -> AssumeRole assumeRole p1 p2 = AssumeRole { _arRoleArn = p1 , _arRoleSessionName = p2 , _arPolicy = Nothing , _arDurationSeconds = Nothing , _arExternalId = Nothing , _arSerialNumber = Nothing , _arTokenCode = Nothing } -- | The duration, in seconds, of the role session. The value can range from -- 900 seconds (15 minutes) to 3600 seconds (1 hour). By default, the value -- is set to 3600 seconds. arDurationSeconds :: Lens' AssumeRole (Maybe Natural) arDurationSeconds = lens _arDurationSeconds (\s a -> s { _arDurationSeconds = a }) . mapping _Nat -- | A unique identifier that is used by third parties to assume a role in -- their customers' accounts. For each role that the third party can assume, -- they should instruct their customers to create a role with the external -- ID that the third party generated. Each time the third party assumes the -- role, they must pass the customer's external ID. The external ID is -- useful in order to help third parties bind a role to the customer who -- created it. For more information about the external ID, see About the -- External ID in Using Temporary Security Credentials. arExternalId :: Lens' AssumeRole (Maybe Text) arExternalId = lens _arExternalId (\s a -> s { _arExternalId = a }) -- | An IAM policy in JSON format. The policy parameter is optional. If you -- pass a policy, the temporary security credentials that are returned by -- the operation have the permissions that are allowed by both the access -- policy of the role that is being assumed, and the policy that you pass. -- This gives you a way to further restrict the permissions for the -- resulting temporary security credentials. You cannot use the passed -- policy to grant permissions that are in excess of those allowed by the -- access policy of the role that is being assumed. For more information, -- see Permissions for AssumeRole in Using Temporary Security Credentials. arPolicy :: Lens' AssumeRole (Maybe Text) arPolicy = lens _arPolicy (\s a -> s { _arPolicy = a }) -- | The Amazon Resource Name (ARN) of the role that the caller is assuming. arRoleArn :: Lens' AssumeRole Text arRoleArn = lens _arRoleArn (\s a -> s { _arRoleArn = a }) -- | An identifier for the assumed role session. The session name is included -- as part of the AssumedRoleUser. arRoleSessionName :: Lens' AssumeRole Text arRoleSessionName = lens _arRoleSessionName (\s a -> s { _arRoleSessionName = a }) -- | The identification number of the MFA device that is associated with the -- user who is making the AssumeRole call. Specify this value if the trust -- policy of the role being assumed includes a condition that requires MFA -- authentication. The value is either the serial number for a hardware -- device (such as GAHT12345678) or an Amazon Resource Name (ARN) for a -- virtual device (such as arn:aws:iam::123456789012:mfa/user). arSerialNumber :: Lens' AssumeRole (Maybe Text) arSerialNumber = lens _arSerialNumber (\s a -> s { _arSerialNumber = a }) -- | The value provided by the MFA device, if the trust policy of the role -- being assumed requires MFA (that is, if the policy includes a condition -- that tests for MFA). If the role being assumed requires MFA and if the -- TokenCode value is missing or expired, the AssumeRole call returns an -- "access denied" error. arTokenCode :: Lens' AssumeRole (Maybe Text) arTokenCode = lens _arTokenCode (\s a -> s { _arTokenCode = a }) data AssumeRoleResponse = AssumeRoleResponse { _arrAssumedRoleUser :: Maybe AssumedRoleUser , _arrCredentials :: Maybe Credentials , _arrPackedPolicySize :: Maybe Nat } deriving (Eq, Show) -- | 'AssumeRoleResponse' constructor. -- -- The fields accessible through corresponding lenses are: -- -- * 'arrAssumedRoleUser' @::@ 'Maybe' 'AssumedRoleUser' -- -- * 'arrCredentials' @::@ 'Maybe' 'Credentials' -- -- * 'arrPackedPolicySize' @::@ 'Maybe' 'Natural' -- assumeRoleResponse :: AssumeRoleResponse assumeRoleResponse = AssumeRoleResponse { _arrCredentials = Nothing , _arrAssumedRoleUser = Nothing , _arrPackedPolicySize = Nothing } -- | The Amazon Resource Name (ARN) and the assumed role ID, which are -- identifiers that you can use to refer to the resulting temporary security -- credentials. For example, you can reference these credentials as a -- principal in a resource-based policy by using the ARN or assumed role ID. -- The ARN and ID include the RoleSessionName that you specified when you -- called AssumeRole. arrAssumedRoleUser :: Lens' AssumeRoleResponse (Maybe AssumedRoleUser) arrAssumedRoleUser = lens _arrAssumedRoleUser (\s a -> s { _arrAssumedRoleUser = a }) -- | The temporary security credentials, which include an access key ID, a -- secret access key, and a security (or session) token. arrCredentials :: Lens' AssumeRoleResponse (Maybe Credentials) arrCredentials = lens _arrCredentials (\s a -> s { _arrCredentials = a }) -- | A percentage value that indicates the size of the policy in packed form. -- The service rejects any policy with a packed size greater than 100 -- percent, which means the policy exceeded the allowed space. arrPackedPolicySize :: Lens' AssumeRoleResponse (Maybe Natural) arrPackedPolicySize = lens _arrPackedPolicySize (\s a -> s { _arrPackedPolicySize = a }) . mapping _Nat instance ToPath AssumeRole where toPath = const "/" instance ToQuery AssumeRole where toQuery AssumeRole{..} = mconcat [ "DurationSeconds" =? _arDurationSeconds , "ExternalId" =? _arExternalId , "Policy" =? _arPolicy , "RoleArn" =? _arRoleArn , "RoleSessionName" =? _arRoleSessionName , "SerialNumber" =? _arSerialNumber , "TokenCode" =? _arTokenCode ] instance ToHeaders AssumeRole instance AWSRequest AssumeRole where type Sv AssumeRole = STS type Rs AssumeRole = AssumeRoleResponse request = post "AssumeRole" response = xmlResponse instance FromXML AssumeRoleResponse where parseXML = withElement "AssumeRoleResult" $ \x -> AssumeRoleResponse <$> x .@? "AssumedRoleUser" <*> x .@? "Credentials" <*> x .@? "PackedPolicySize"