Skip to content

Commit

Permalink
#3: Updates commands on README
Browse files Browse the repository at this point in the history 
- adds the remove login command
- fixes link to MIT license
/
  • Loading branch information
Jessé Moraes Braga committed Jan 26, 2023
1 parent ed400d6 commit 3f859b4
Showing 1 changed file with 34 additions and 21 deletions.
55 changes: 34 additions & 21 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# OTC-Auth
Open Source CLI for the Authorization with the Open Telekom Cloud.

[![MIT License](https://img.shields.io/apm/l/atomic-design-ui.svg?)](https://github.com/iits-consulting/otc-auth/blob/main/LICENSE)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/iits-consulting/otc-auth/blob/main/LICENSE)
![Build](https://github.com/iits-consulting/otc-auth/workflows/Build/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/iits-consulting/otc-auth)](https://goreportcard.com/report/github.com/iits-consulting/otc-auth)
![CodeQL](https://github.com/iits-consulting/otc-auth/workflows/CodeQL/badge.svg)
Expand All @@ -17,22 +17,22 @@ This tool can also be used to manage (create) a pair of Access Key/ Secret Key i
https://user-images.githubusercontent.com/19291722/208880256-b0da924e-254e-4bc4-b9ee-396c43234a5b.mp4

## Install

Binary downloads of the Helm client can be found on the [Releases page](https://github.com/iits-consulting/otc-auth/releases).

Unpack the helm binary and add it to your PATH and you are good to go!
You can download the binary for your system in the [releases page](https://github.com/iits-consulting/otc-auth/releases).
Unpack the binary and add it to your PATH and you are good to go!

## Login
Use the `login` command to retrieve an unscoped token either by logging in directly with the Service Provider or through an IdP. You can see the help page by entering `login --help` or `login -h`. There are three log in options (`iam`, `idp-saml`, and `idp-oidc`) and one of them must be provided.

### Service Provider Login (IAM)
To log in directly with the Open Telekom Cloud's IAM, you will have to supply the domain name you're attempting to log in to (usually starting with "OTC-EU", following the region and a longer identifier), your username and password.

`login iam --os-username <username> --os-password <password> --os-domain-name <domain_name>`
`otc-auth login iam --os-username <username> --os-password <password> --os-domain-name <domain_name>`

Alternatively, it is possible to use MFA if that's desired and/or required. In this case both arguments `--os-user-domain-id` and `--totp` are required. The user id can be obtained in the "My Credentials" page on the OTC.
In addition, it is possible to use MFA if that's desired and/or required. In this case both arguments `--os-user-domain-id` and `--totp` are required. The user id can be obtained in the "My Credentials" page on the OTC.

`login iam --os-username <username> --os-password <password> --os-domain-name <domain_name> --os-user-domain-id <user_domain_id> --totp <6_digit_token>`
```
otc-auth login iam --os-username <username> --os-password <password> --os-domain-name <domain_name> --os-user-domain-id <user_domain_id> --totp <6_digit_token>
```

The OTP Token is 6-digit long and refreshes every 30 seconds. For more information on MFA please refer to the [OTC's documentation](https://docs.otc.t-systems.com/en-us/usermanual/iam/iam_10_0002.html).

Expand All @@ -42,34 +42,45 @@ You can log in with an external IdP using either the `saml` or the `oidc` protoc
#### External IdP and SAML
The SAML login flow is SP initiated and requires you to send username and password to the SP. The SP then authorizes you with the configured IdP and returns either an unscoped token or an error, if the user is not allowed to log in.

`login idp-saml --os-username <username> --os-password <password> --idp-name <idp_name> --os-auth-url <authorization_url>`
```otc-auth login idp-saml --os-username <username> --os-password <password> --idp-name <idp_name> --idp-url <authorization_url> --os-domain-name <os_domain_name>```

At the moment, no MFA is supported for this login flow.

#### External IdP and OIDC
The OIDC login flow is user initiated and will open a browser window with the IdP's authorization URL for the user to log in as desired. This flow does support MFA (this requires it to be configured on the IdP). After being successfully authenticated with the IdP, the SP will be contacted with the corresponding credentials and will return either an unscoped token or an error, if the user is not allowed to log in.

`login idp-oidc --idp-name <idp_name> --os-auth-url <authorization_url> --client-id <client_id> --client-secret <client_secret>`
```otc-auth login idp-oidc --idp-name <idp_name> --idp-url <authorization_url> --client-id <client_id> --os-domain-name <os_domain_name> [--client-secret <client_secret>]```

The argument `--client-id` is required, but the argument `--client-secret` is only needed if configured on the IdP.

### Remove Login
Clouds are differentiated by their identifier `--os-domain-name`. To delete a cloud, use the `remove` command.

`otc-auth login remove --os-domain-name <os_domain_name>`

## List Projects
It is possible to get a list of all projects in the current cloud. For that, use the following command.

`otc-auth projects list`

## Cloud Container Engine
Use the `cce` command to retrieve a list of available clusters in your project and/or get the remote kube configuration file. You can see the help page by entering `cce --help` or `cce -h`.

To retrieve a list of clusters for a project use the following command:
To retrieve a list of clusters for a project use the following command. The project name will be checked against the ones in the cloud at the moment of the request.
If the desired project isn't found, you will receive an error message.

`cce list --os-project-name <project_name>`
`otc-auth cce list --os-domain-name <os_domain_name> --os-project-name <project_name>`

To retrieve the remote kube configuration file (and merge to your local one) use the following command:

`cce get-kube-config --os-project-name <project_name> --cluster <cluster_name>`
`otc-auth cce get-kube-config --os-domain-name <os_domain_name> --os-project-name <project_name> --cluster <cluster_name>`

Alternatively you can pass the argument `--days-valid` to set the period of days the configuration will be valid, the default is 7 days.

## Manage Access Key and Secret Key Pair
You can use the OTC-Auth tool to download the AK/SK pair directly from the OTC. It will download the "ak-sk-env.sh" file to the current directory. The file contains four environment variables.

`otc-auth access-token create`
`otc-auth access-token create --os-domain-name <os_domain_name>`

The "ak-sk-env.sh" file must then be sourced before you can start using the environment variables.

Expand All @@ -78,13 +89,15 @@ The OTC-Auth tool also provides environment variables for all the required argum

| Environment Variable | Argument | Short | Description |
|----------------------|-----------------------|:-----:|-----------------------------------------------|
| OS_AUTH_URL | `--os-auth-url` | N/A | |
| OS_USERNAME | `--os-username` | `u` | Username (iam or idp) |
| OS_PASSWORD | `--os-password` | `p` | Password (iam or idp) |
| OS_DOMAIN_NAME | `--os-domain-name` | `d` | Domain Name from OTC Tenant |
| OS_USER_DOMAIN_ID | `--os-user-domain-id` | `i` | User id from OTC Tenant |
| IDP_NAME | `--idp-name` | `i` | Identity Provider name (as configured on OTC) |
| CLIENT_ID | `--client-id` | `c` | Client id as configured on the IdP |
| CLIENT_SECRET | `--client-secret` | `s` | Client secret as configured on the IdP |
| OS_PROJECT_NAME | `--os-project-name` | `p` | Project name on the OTC |
| CLUSTER_NAME | `--cluster` | `c` | Cluster name on the OTC |
| OS_DOMAIN_NAME | `--os-domain-name` | `d` | Domain Name from OTC Tenant |
| OS_PASSWORD | `--os-password` | `p` | Password (iam or idp) |
| OS_PROJECT_NAME | `--os-project-name` | `p` | Project name on the OTC |
| OS_USER_DOMAIN_ID | `--os-user-domain-id` | `i` | User id from OTC Tenant |
| OS_USERNAME | `--os-username` | `u` | Username (iam or idp) |
| IDP_NAME | `--idp-name` | `i` | Identity Provider name (as configured on OTC) |
| IDP_URL | `--idp-url` | N/A | Authorization endpoint on the IDP |


0 comments on commit 3f859b4

Please sign in to comment.