Skip to content

Latest commit

 

History

History
executable file
·
805 lines (655 loc) · 28.6 KB

API.md

File metadata and controls

executable file
·
805 lines (655 loc) · 28.6 KB

Classes

alks

ALKS JavaScript API

Typedefs

skypieaAccount : Object

Skypiea Account

accountOwners : Object

AccountUserDetails

account : Object

AWS Account

credentials : Object

AWS STS Credentials

awsRoleType : Object

AWS IAM role type

customRole : Object

Custom AWS IAM account role

awsAccountRole : Object

AWS account role type

alksUser : Object

ALKS User representation

AccessKeys : Object

Response containing access keys.

alks

ALKS JavaScript API

Kind: global class

alks.create(props) ⇒ alks

Returns a new instance of alks with pre-defined properties (which don't need to be supplied to every method).

Any of the properties required by other methods can be specified here.

Properties present on the current object are carried through to the newly created one.

Kind: instance method of alks
Params

  • props Object - An object containing settings for the new ALKS object

Example

var myAlks = alks.create({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
})

myAlks.getKeys({
  account: 'anAccount',
  role: 'PowerUser',
  sessionTime: 2
}).then((creds) => {
  // creds.accessKey, creds.secretKey, creds.sessionToken
})

alks.getAccounts(props) ⇒ Promise.<Array.<account>>

Returns a Promise for an array of AWS accounts (and roles) accessible by the user

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request

Example

alks.getAccounts({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
}).then((accounts) => {
  // accounts[0].account, accounts[0].role, accounts[0].iamKeyActive, accounts[0].maxKeyDuration, accounts[0].skypieaAccount
})

alks.getKeys(props) ⇒ Promise.<credentials>

Returns a Promise for AWS STS credentials from ALKS.

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .account string - The AWS account to use when provisioning the credentials
    • .role string - The ALKS role to use when provisioning the credentials
    • .sessionTime string - The session length for the credentials

Example

alks.getKeys({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  account: 'anAccount',
  role: 'PowerUser',
  sessionTime: 2
}).then((creds) => {
  // creds.accessKey, creds.secretKey, creds.sessionToken, creds.consoleURL
})

alks.getIAMKeys(props) ⇒ Promise.<credentials>

Returns a Promise for AWS STS credentials with IAM permissions from ALKS.

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .account string - The AWS account to use when provisioning the credentials
    • .role string - The ALKS role to use when provisioning the credentials
    • .sessionTime number - The session length for the credentials

Example

alks.getIAMKeys({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  account: 'anAccount',
  role: 'IAMAdmin',
  sessionTime: 1
}).then((creds) => {
  // creds.accessKey, creds.secretKey, creds.sessionToken, creds.consoleURL
})

alks.getAllAWSRoleTypes(props) ⇒ Promise.<Array.<awsRoleType>>

Returns a Promise for an array of all available role types (AWS IAM role types, custom role types) and their details

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request

Example

alks.getAllAWSRoleTypes({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
}).then((roleTypes) {
  // roleTypes[i].roleTypeName, roleTypes[i].defaultArns, roleTypes[i].trustRelationship
})

alks.getAWSRoleTypes(props) ⇒ Promise.<Array.<string>>

Deprecated

Returns a Promise for an array of available AWS IAM role types

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request

Example

alks.getAWSRoleTypes({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
}).then((roleTypes) {
  // ['AWS Lambda', 'Amazon EC2', ... ]
})

alks.getNonServiceAWSRoleTypes(props) ⇒ Promise.<Array.<string>>

Deprecated

Returns a Promise for an array of available custom role types

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request

Example

alks.getNonServiceAWSRoleTypes({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
}).then((roleTypes) => {
  // ['AWS Lambda', 'Amazon EC2', ...]
})

alks.createRole(props) ⇒ Promise.<customRole>

Returns a Promise for the results of creating a new custom AWS IAM account role

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .account string - The user's account associated with the custom role
    • .role string - The user's role associated with the account
    • .roleName string - The name of the custom AWS IAM role to create
    • .roleType string - The type of AWS role to use when creating the new role
    • .includeDefaultPolicy number - Whether to include the default policy in the new role (1 = yes, 0 = no)
    • .enableAlksAccess boolean - Whether the role has a machine identity

Example

alks.createRole({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  account: 'anAccount',
  role: 'IAMAdmin',
  roleName: 'awsRoleName',
  roleType: 'Amazon EC2',
  includeDefaultPolicy: 1,
  enableAlksAccess: true
}).then((role) => {
  // role.roleArn, role.denyArns, role.instanceProfileArn, role.addedRoleToInstanceProfile
})

alks.createNonServiceRole(props) ⇒ Promise.<customRole>

Returns a Promise for the results of creating a new custom AWS IAM trust role

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .account string - The user's account associated with the custom role
    • .role string - The user's role associated with the account
    • .roleName string - The name of the custom AWS IAM role to create
    • .roleType string - The type of AWS role to use when creating the new role
    • .includeDefaultPolicy number - Whether to include the default policy in the new role (1 = yes, 0 = no)
    • .trustArn string - The Arn of the existing role to trust
    • .trustType string - Whether the trust is 'Cross Account' or 'Inner Account'
    • .enableAlksAccess boolean - Whether the role has a machine identity

Example

alks.createNonServiceRole({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  account: 'anAccount',
  role: 'IAMAdmin',
  roleName: 'awsRoleName',
  roleType: 'Amazon EC2',
  includeDefaultPolicy: 1,
  trustArn: 'anExistingRoleArn',
  trustType: 'Cross Account',
  enableAlksAccess: true
}).then((role) => {
  // role.roleArn, role.denyArns, role.instanceProfileArn, role.addedRoleToInstanceProfile
})

alks.awsAccountRoles(props) ⇒ Promise.<Array.<awsAccountRole>>

Returns a Promise for an array of AWS account roles

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .account string - The account number to get AWS roles for

Example

alks.awsAccountRoles({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  account: '1234567890',
}).then((roles) => {
  // roles[i].roleArn, roles[i].isMachineIdentity, roles[i].assumeRolePolicyDocument
})

alks.listAWSAccountRoles(props) ⇒ Promise.<Array.<string>>

Deprecated

Returns a Promise for an array of AWS custom AWS IAM account roles

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .account string - The user's account associated with the custom role
    • .role string - The user's role associated with the account

Example

alks.listAWSAccountRoles({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  account: 'anAccount',
  role: 'IAMAdmin',
}).then((roleNames) => {
  // ['customRole1', 'customRole2', ...]
})

alks.getAccountRole(props) ⇒ Promise.<string>

Returns a Promise for the Amazon Resource Name (ARN) of a custom AWS IAM account role

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .account string - The user's account associated with the custom role
    • .role string - The user's role associated with the account
    • .roleName string - The name of the custom AWS IAM role

Example

alks.getAccountRole({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  account: 'anAccount',
  role: 'IAMAdmin',
  roleName: 'awsRoleName'
}).then((roleARN) => {
  // arn:aws:iam::123:role/acct-managed/awsRoleName
})

alks.deleteRole(props) ⇒ Promise.<boolean>

Returns a Promise for a boolean "true" indicating the role was deleted

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .account string - The user's account associated with the custom role
    • .role string - The user's role associated with the account
    • .roleName string - The name of the custom AWS IAM role

Example

alks.deleteRole({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  account: 'anAccount',
  role: 'IAMAdmin',
  roleName: 'awsRoleName'
}).then(() => {
  // success!
})

alks.addRoleMachineIdentity(props) ⇒ Promise.<string>

Returns a Promise for a string arn indicating the role was enabled for machine identity

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .roleArn string - The Amazon Resource Name (ARN) associated with the role

Example

alks.addRoleMachineIdentity({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  roleARN: 'arn:aws:iam::123:role/acct-managed/awsRoleName'
}).then((roleARN) => {
  // arn:aws:iam::123:role/acct-managed/awsRoleName
})

alks.deleteRoleMachineIdentity(props) ⇒ Promise.<string>

Returns a Promise for a string arn indicating the role was disabled for machine identity

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .roleArn string - The Amazon Resource Name (ARN) associated with the role

Example

alks.deleteRoleMachineIdentity({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  roleARN: 'arn:aws:iam::123:role/acct-managed/awsRoleName'
}).then((roleARN) => {
  // arn:aws:iam::123:role/acct-managed/awsRoleName
})

alks.getUserAccess(props) ⇒ Promise.<Array.<alksUser>>

Returns a Promise for a list of users who have access to the given account

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .accountId string - The accountId used to find which users have access to the account

Example

alks.getUserAccess({
   baseUrl: 'https://your.alks-host.com',
   accessToken: 'abc123',
   accountId: '012345678910',
}).then((users) => {
   // users[i].sAMAccountName, users[i].displayName, users[i].email, users[i].title, users[i].department
})

alks.getUserAccessByRole(props) ⇒ Promise.<Object>

Returns a Promise for a map of role names to the list of users with that role for a given account

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .accountId string - The accountId used to find which users have access to the account

Example

alks.getUserAccess({
   baseUrl: 'https://your.alks-host.com',
   accessToken: 'abc123',
   accountId: '012345678910',
}).then((users) => {
   // users['Admin'].sAMAccountName, users['Admin'].displayName, users['Admin'].email, users['Admin'].title, users['Admin'].department
})

alks.getUserRoleAccess(props) ⇒ Promise.<Array.<string>>

Returns a Promise for a list of roles a user has for a given account

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .accountId string - The accountId used to find which users have access to the account
    • .sAMAccountName string - The network id of the user to lookup

Example

alks.getUserRoleAccess({
   baseUrl: 'https://your.alks-host.com',
   accessToken: 'abc123',
   accountId: '012345678910',
   sAMAccountName: 'bob1',
}).then((roles) => {
   // ['Admin', 'LabAdmin', ...]
})

alks.createAccessKeys(props) ⇒ Promise.<AccessKeys>

Returns a Promise for the results of creating new IAM user and long-term access keys

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .account string - The user's account associated with the custom role
    • .role string - The user's role associated with the account
    • .iamUserName string - The name of the IAM user to create

Example

alks.createAccessKeys({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  account: 'anAccount',
  role: 'IAMAdmin',
  iamUserName: 'iamUserName'
}).then((user) => {
  // user.iamUserArn, user.accessKey, user.secretKey, user.addedIAMUserToGroup
})

alks.deleteIAMUser(props) ⇒ Promise.<boolean>

Returns a Promise for a boolean "true" indicating the IAM user and long-term access keys were deleted

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .baseUrl string - The base URL of the ALKS service
    • .accessToken string - The OAuth2 access token used to authorize the request
    • .account string - The user's account associated with the custom role
    • .role string - The user's role associated with the account
    • .iamUserName string - The name of the IAM user to delete

Example

alks.deleteIAMUser({
  baseUrl: 'https://your.alks-host.com',
  accessToken: 'abc123',
  account: 'anAccount',
  role: 'IAMAdmin',
  iamUserName: 'iamUserName'
}).then(() => {
  // success!
})

alks.version(props) ⇒ Promise.<Object>

Returns the version of the ALKS Rest API

Kind: instance method of alks
Params

  • props Object - An object containing the following properties

Example

alks.version({
  ...
}).then((data) => {
  // data.version
})

alks.getLoginRole(props) ⇒ Promise.<Object>

Returns information about one of the roles used to generate keys

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .accountId string - The 12-digit account ID associated with the custom role
    • .role string - The user's role associated with the account
    • .maxKeyDuration number - The maximum key duration for this account

Example

alks.getLoginRole({
  ...
}).then((loginRole) => {
  // loginRole.account, loginRole.role, loginRole.iamKeyActive, loginRole.maxKeyDuration
})

alks.getAccessToken(props) ⇒ Promise.<Object>

Exchanges a refresh token for an access token

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • .refreshToken string - the refresh token to exchange

Example

alks.getAccessToken({
  ...
}).then((data) => {
  // data.accessToken, data.expiresIn
})

alks.getRefreshTokens(props) ⇒ Array.<Object>

Returns a list of a user's refresh tokens (Does not return the full token)

Kind: instance method of alks
Params

  • props Object - An object containing the following properties

Example

alks.getRefreshTokens({
  ...
}).then((tokens) => {
  // token[i].clientId, token[i].id, token[i].userId, token[i].value
})

alks.revoke(props) ⇒ boolean

Revokes a refresh or access token

Kind: instance method of alks
Params

  • props Object - An object containing the following properties
    • [.token] string - the access or refresh token to revoke (Required if tokenId not specified)
    • [.tokenId] string - the ID of the refresh token to revoke (Required if token not specified)

Example

alks.revoke({
  token: '...',
  ...
}).then((success) => {
  // success == true
})

// or

alks.revoke({
  tokenId: '...',
  ...
}).then((success) => {
  // success == true
})

skypieaAccount : Object

Skypiea Account

Kind: global typedef

accountOwners : Object

AccountUserDetails

Kind: global typedef
Params

  • samAccountName string - the samAccountName of the user
  • email string - the email of the user
  • href string - the href self link

account : Object

AWS Account

Kind: global typedef
Properties

  • account string - The name of the account
  • role string - The user's role in this account
  • iamKeyActive boolean - Whether credentials with IAM permissions can be provisioned from this account
  • maxKeyDuration number - The maximum key duration for this account
  • skypieaAccount skypieaAccount - extra information about the account from Skypiea

credentials : Object

AWS STS Credentials

Kind: global typedef
Properties

  • accessKey string - AWS access key
  • secretKey string - AWS secret key
  • sessionToken string - AWS STS session token

awsRoleType : Object

AWS IAM role type

Kind: global typedef
Properties

  • roleTypeName string - The AWS IAM role type name
  • defaultArns Array.<string> - The default ARNs (default policies) associated with this role
  • trustRelationship Object - The AWS trust relationship document associated with this role
  • instanceProfile boolean - Whether this role is an instance profile

customRole : Object

Custom AWS IAM account role

Kind: global typedef
Properties

  • roleArn string - The Amazon Resource Name (ARN) associated with the new role
  • denyArns string - The ARNs for the deny policies associated with this role
  • instanceProfileArn string - The Instance Profile ARN associated with this role
  • addedRoleToInstanceProfile boolean - Whether this role was added to an Instance Profile

awsAccountRole : Object

AWS account role type

Kind: global typedef
Properties

  • roleArn string - The AWS Role ARN
  • isMachineIdentity boolean - true|false value of if this role is a machine identity
  • assumeRolePolicyDocument Object - The AWS assume role policy document associated with this role

alksUser : Object

ALKS User representation

Kind: global typedef
Properties

  • sAMAccountName string - The network id
  • displayName string - The display nme
  • email string - The user email
  • title string - The user title
  • department string - The user department

AccessKeys : Object

Response containing access keys.

Kind: global typedef
Properties

  • iamUserArn string - the arn of the IAM user owning the long term access keys
  • accessKey string - the long term access key
  • secretKey string - the secret key for the long term access key
  • addedIAMUserToGroup boolean - whether the user was successfuly added to the deny policy group