A Clojure AWS library that provides

• Authentication using various Credential Providers
• Authentication using MFA, optionally
• Assume Roles https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html

Installation

;; Add below to deps.edn

{omnyway-labs/saw
  {:git/url "https://github.com/omnyway-labs/saw.git"
   :sha "3ac408b6c7f7574c3280d99959a3b542ecc4d7f2"
   :tag "0.2.13"}

;; or
{saw {:mvn/version "0.2.13"}}

(require '[saw.core :as saw])

;; use any of the following
(saw/login provider)
(saw/login provider mfa-code)
(saw/login provider mfa-code mfa-role)

See following examples for usage

Usage

Basic Providers

(saw/login provider)

Examples:

(saw/login {:provider :static
            :region "us-east-1"
            :access-key "xxx"
            :secret-key "xxx"})

(saw/login {:provider :profile
            :profile :default
            :region "us-east-1"})

(saw/login {:provider :env
            :region "us-east-1"})
;; make sure the env vars AWS_ACCESS_KEY and AWS_SECRET_KEY_ID
;; are set when using env provider

(saw/login {:provider :default
            :region "us-east-1"})

Provider with MFA

(saw/login provider mfa-code mfa-role)

;; or set the AWS_MFA_ARN in an env variable
export AWS_MFA_ARN=arn:aws:iam::xxx:mfa/icy
(saw/login provider mfa-code)

When MFA is used to create a session, the same session can be used to assume multiple Roles. The session is persisted in ~/.aws/session file

Assume Role

With the above CredentialsProvider object, created using with or without MFA, it is possible to assume a different relevant IAM role

(-> (saw/login provider)
    (saw/assume profile))

;;example:

(-> (saw/login {:provider :profile :profile :default :region "us-east-1"})
    (saw/assume profile))

where profile is an entry in ~/.aws/credentials file

[default]
aws_access_key_id=xxx
aws_secret_access_key=xxx
region=us-east-1
[staging]
role_arn=arn:aws:iam::xxx:role/StagingUserRole
region=us-east-1
source_profile=mfa
[prod]
role_arn=arn:aws:iam::xxx:role/ProdUserRole
region=us-east-1
source_profile=mfa

Assume Role works with MFA too:

(-> (saw/login provider mfa-code)
    (saw/assume :staging))

;; or just assume after a login
(saw/assume :staging)
(saw/assume :production)

We can also pass in the role-arn and region without needing it to be in a profile in ~/.aws/credentials

(-> (saw/login provider)
    (saw/assume "arn:aws:iam::xxx:role/StagingUserRole" "us-east-1"))

;;=> creds

Using with an AWS service client

login returns the CredentialsProvider object that can be used to create the AWS service clients. Example:

(import '[com.amazonaws.services.s3
          AmazonS3ClientBuilder])

(let [creds (saw/login provider)
      client (-> (AmazonS3ClientBuilder/standard)
                 (.withCredentials creds)
                 (.withRegion (saw/region))
                 .build)])

;; or when using assume

(let [creds (-> (saw/login provider) (saw/assume profile)]
      (-> (AmazonS3ClientBuilder/standard)
          (.withCredentials creds)
          (.withRegion (saw/region))
          .build)

(.withCredentials (saw/creds)) works too.

(saw/region) returns the current region set during login or assume

Errors

ex-data throws error in the format

(ex-data *e)

{:error error-id :message error-message :type :saw-error :cause cause}

Following are some known error-ids:

(:assume-role-failed
 :invalid-creds-object
 :mfa-code-not-string
 :profile-not-found
 :provider-not-resolved
 :provider-not-supported
 :region-not-found
 :region-not-found-in-profile
 :role-arn-not-found
 :role-arn-not-found-in-profile
 :session-cache-failed
 :session-create-failed
 :session-empty-cache-failed
 :session-lookup-failed
 :session-not-found
 :session-validaton-failed)

Session Utils

;; to lookup session
(saw/session)

;; to validate the session
(saw/validate-session region)
(saw/validate-session "us-east-1")

The Session Timeout is configurable via the AWS_SESSION_TIMEOUT env variable (seconds).

License - Apache 2.0

Copyright 2020 Omnyway Inc.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.