🐛 CredentialProcess is unusable

 - Prevent session reuse from CredentialProcess

 - Introduce okta-credential-process command

 - Provide manpage-like docs

Future work: use [ronn](https://github.com/rtomayko/ronn) to make real
man pages at build time

Resolves oktadev#232

Readme.MD

@@ -97,6 +97,10 @@ Run the program again to see session resumption (you won't be asked for Okta cre
 okta-aws test sts get-caller-identity
 ```
 
+## Reference
+* [okta-listroles(1)](docs/man/okta-listroles.1.md)
+* [okta-credential_process(1)](docs/man/okta-credential_process.1.md)
+
 ## Compiling the application
 
 The application was built and compiled with [JetBrains' IntelliJ IDEA](https://www.jetbrains.com/idea/). Note that you don't have to compile the application in order to be able to execute it, since the compiled executable (a JAR file) is available [on GitHub](https://github.com/oktadeveloper/okta-aws-cli-assume-role/releases).

bin/install.sh

@@ -84,6 +84,15 @@ env OKTA_PROFILE=$profile java -classpath ~/.okta/okta-aws-cli.jar com.okta.tool
 ' > "$PREFIX/bin/withokta"
 chmod +x "$PREFIX/bin/withokta"
 
+# Create okta-credential_process command
+echo '#!/bin/bash
+roleARN="$1"
+shift;
+env OKTA_AWS_ROLE_TO_ASSUME="$roleARN" \
+ java -classpath ~/.okta/okta-aws-cli.jar com.okta.tools.CredentialProcess
+' > "$PREFIX/bin/okta-credential_process"
+chmod +x "$PREFIX/bin/okta-credential_process"
+
 # Create okta-listroles command
 echo '#!/bin/bash
 java -classpath ~/.okta/okta-aws-cli.jar com.okta.tools.ListRoles

docs/man/okta-credential_process.1.md

@@ -0,0 +1,70 @@
+# okta-credential_process(1) -- Output AWS credentials in JSON format.
+
+## SYNOPSIS
+
+ okta-credential_process <role ARN>
+
+## DESCRIPTION
+
+The okta-credential_process tool allows you to authenticate to Okta and
+assume an AWS IAM Role.
+
+## FIELDS
+
+ "Version"
+
+ The version of the credential_process interface defined by the AWS
+ CLI docs here:
+ https://docs.aws.amazon.com/cli/latest/topic/config-vars.html
+
+ "AccessKeyId"
+
+ The AWS IAM (Identity and Access Management) access key ID.
+
+ "SecretAccessKey"
+
+ The AWS IAM secret access key.
+
+ "SessionToken"
+
+ The AWS STS (Security Token Service) session token.
+
+ "Expiration"
+
+ The timestamp at which the credentials will expire in ISO8601
+ format. 
+
+## EXAMPLES
+
+Add something like the following to ~/.aws/config:
+```ini
+[profile dev]
+credential_process = okta-credential_process arn:aws:iam::123456789012:role/ExampleRole
+```
+* Replace arn:aws:iam::123456789012:role/ExampleRole with the real IAM
+ Role ARN (use okta-listroles to see available role ARNs)
+
+Use the profile as follows:
+```bash
+aws --profile dev sts get-caller-identity
+```
+
+This also works with scripts using the AWS SDK for Python (aka boto3).
+
+```python
+import boto3
+dev = boto3.session.Session(profile_name='dev')
+s3 = dev.resource('s3')
+for bucket in s3.buckets.all():
+ print(bucket.name)
+```
+
+## NOTES
+
+AWS CLI doesn't cache the credentials, neither does okta-aws-cli.
+Credentials will be fetched by AWS CLI every time it runs (irregardless
+of expiry)
+
+# SEE ALSO
+
+[okta-listroles(1)](okta-listroles.1.md)

docs/man/okta-listroles.1.md

@@ -0,0 +1,67 @@
+# okta-listroles(1) -- Output a list of roles available to assume.
+
+## SYNOPSIS
+
+ okta-listroles
+
+## DESCRIPTION
+
+The okta-listroles tool allows you to authenticate to Okta and list the
+roles that are available to be assumed.
+
+## FIELDS
+
+ "accountName"
+
+ The AWS account name and number the role belongs to.
+
+ "roleOptions"
+
+ A list of roleName and AWS IAM roleArn pairs available without a given account.
+
+ "roleName"
+
+ The name of the AWS IAM Role.
+
+ "roleARN"
+
+ The ARN (Amazon Resource Name) of the AWS IAM Role.
+
+## EXAMPLES
+
+Running a command like this:
+
+ okta-listroles
+
+Will prompt for Okta credentials (or reuse your session) and output
+something like this to standard output:
+
+
+ [
+  {
+  "accountName": "Account: example-corp (123456789012)",
+  "roleOptions": [
+  {
+  "roleName": "Admin",
+  "roleArn": "arn:aws:iam::123456789012:role/Admin"
+  }
+  ]
+  },
+  {
+  "accountName": "Account: example-research (654321234567)",
+  "roleOptions": [
+  {
+  "roleName": "Admin",
+  "roleArn": "arn:aws:iam::654321234567:role/Admin"
+  }
+  {
+  "roleName": "ReadOnly",
+  "roleArn": "arn:aws:iam::654321234567:role/ReadOnly"
+  }
+  ]
+  }
+ ]
+
+# SEE ALSO
+
+[okta-credential_process(1)](okta-credential_process.1.md)

src/main/java/com/okta/tools/CredentialProcess.java

@@ -25,6 +25,7 @@
 public class CredentialProcess {
  public static void main(String[] args) throws Exception {
  OktaAwsCliEnvironment environment = OktaAwsConfig.loadEnvironment();
+ environment.oktaEnvMode = true;
  Instant startInstant = Instant.now();
  Duration sessionLength = Duration.of(environment.stsDuration, ChronoUnit.SECONDS);
  Instant expirationInstant = startInstant.plus(sessionLength);

src/main/java/com/okta/tools/OktaAwsCliEnvironment.java

@@ -16,7 +16,7 @@ public class OktaAwsCliEnvironment {
 
  public int stsDuration;
  public final String awsRegion;
- public final boolean oktaEnvMode;
+ public boolean oktaEnvMode;
 
  public OktaAwsCliEnvironment()
  {