Using the Tachyon PowerShell Toolkit with platform-neutral authentication
How to use the PowerShell toolkit when connecting to a Tachyon platform server that is configured for platform-neutral authentication.
Authenticating interactively
You can authenticate interactively by simply connecting to the server with the set-tachyonserver cmdlet.
For example, to connect to the platform server auth4ui2.platformeng.cloud.1e.com
set-tachyonserver auth4ui2.platformeng.cloud.1e.com
You will see a browser prompt from the configured identity provider. After entering a valid user and password, you will see a browser screen that says you have been successfully authenticated.
PowerShell session can’t control the active window, therefore you must then manually switch back to your active PowerShell session. You will now be able to interact with the platform.
How does this work?
The PS toolkit opens a WebSocket connection to the platform, just like a browser client would. Because it’s not running in the browser, it then launches the user’s default browser and asks it to go to the authentication URL that the platform returned via the websocket connection.
After that, authentication occurs between the IdP and the platform, because the redirect URL specified in the IdP configuration points back to the platform. Ultimately, the token is then returned to PS via the websocket connection, which is then closed.
Retrieving the current token
When you authenticate to a platform-neutral server, you receive a token. This token is used automatically by the PowerShell toolkit when making further API calls to the platform. You can retrieve the current token at any point using the get-tachyonauthtoken cmdlet.
The IssueAppId, IssuePrincipal and IssueCertSubject members are empty here because this is an internal PowerShell object that is used for both interactive and non-interactive tokens.
Interactive tokens can be automatically refreshed and so these members are not required.
You can see the actual token decoded by specifying the optional -decode parameter.
Note that the type member is 0. This specifies that the token was acquired interactively.
Refreshing the token
Interactive tokens can be refreshed. You call the update-tachyonauthtoken cmdlet to do this.
You can only refresh the token a limited number of times. This is configurable in the tenantconfig.json file that configures the platform.
When you exceed this refresh count, the token refresh is rejected and you need to reauthenticate to gain a fresh token.
Authenticating non-interactively
You can also authenticate non-interactively. To do this via an internally-generated signed JWT, you must have access to a certificate which has been configured on the identity provider used by the platform. You keep a copy of the certificate in your local machine personal certificate store. Your account must have access to the private key of this certificate.
You can also authenticate non-interactively using a platform token. This does not require any interaction with the external identity provider. This is discussed further in the section ‘Authenticating non-interactively using a platform token’ below.
Note
In the examples, the certificate is retrieved by subject, using the -CertSubject parameter. You can also specify a certificate thumbprint instead, using the -CertThumbprint parameter. If both are specified, the thumbprint takes precedence over the subject.
Authenticating non-interactively using a JWT
This is how most external integration subsystems will connect. The customer’s identity provider will validate that the submitted JWT (created internally by the PowerShell toolkit) is validly signed.
You specify additional parameters to the set-tachyonserver cmdlet as shown below:
set-tachyonserver urth-dev.urth.local -AppId 0c83091d-fc2f-40b5-8aca-940e4cf5f9b5 -CertSubject "CN=Corellian"
For the shared identity provider instance, these two parameters will always be the same. Each customer environment will have a unique defined application Id and certificate subject, so you need to know what these are, and have a copy of the certificate, before you can connect.
Internally, an object known as a Json Web Token (JWT) is created and digitally signed with the certificate. It is then sent to the platform, which in turn passes it to the identity provider for validation. On success, an internal token is created for a Tachyon principal and then returned.
If you examine the returned token as before, you see it is very similar, except that the Type is set to 1.
Note
The principal associated with the token is determined through a process known as ‘principal mapping’. This is discussed in more detail in the section on principal mapping below.
This indicates that the token is a non-interactive token. It cannot be refreshed.
Authenticating non-interactively using a Platform Token
Tachyon platform components authenticate with each other using a special token called a platform token. Although this is identical in format to interactive and non-interactive tokens, it is marked with a Type value of 2 to distinguish it.
Platform tokens are associated with a fixed Tachyon principal, TachyonPlatform. This principal has been granted roles in Tachyon RBAC that allow it to perform a wide range of privileged functions in the system.
Platform tokens are not authenticated by the customer’s external identity provider. Instead, they are signed and verified using an internal certificate that is used only within the platform.
There are scenarios where you may wish to authenticate using a platform token. To do so, you will require access to the platform token signing certificate, which must be in your local machine certificate store. You must have access to the private key of this certificate using your current logged-in Windows identity.
You can then request that you authenticate using this certificate and receive a platform token. The PowerShell toolkit will then use this for all subsequent activity. This is useful if you were, for example, interacting with the Tachyon platform during SaaS provisioning, because there is no reliance on the external identity provider and, unlike JWT-based authentication, you do not have to set up principal mapping entries.
For example:
set-tachyonserver urth-dev.urth.local -CertSubject "CN=Corellian" -AsPlatform
Note
This example uses a certificate that normally would NOT be set up to sign platform tokens - however, in test lab scenarios you can use a single certificate for both JWT signing and platform token signing. You should never do this in production environments, because the platform token signing certificate is not intended to be given to the customer, and the JWT signing certificate DOES require that the customer has access to the certificate.
Note
When you sign in with the Platform Token, the RBAC permissions that you get are those assigned to the TachyonPlatform principal. Contrary to what you might think, this account does not have Full Administrator permissions by default, so this type of login does not give you unlimited privileges on the platform unless you first change the role assignment for the TachyonPlatform principal.
Refreshing a non-interactive token
The PowerShell toolkit will refresh a non-interactive token by using the update-tachyonauthtoken cmdlet. Although the token itself, unlike an interactive token, can’t be directly refreshed, the toolkit creates a fresh non-interactive token by creating a fresh JWT (or platform token assertion) and signing it, then submitting it. It does not require you to re-supply the certificate subject, thumbprint or application Id because it remembers these from when the token was first created.
Principal mapping for non-interactive tokens
When you authenticate interactively, the principal that you are associated with is, clearly, the principal you supply as part of your logon credentials.
When you authenticate non-interactively using a JWT, the principal that you are associated with is derived through a principal mapping operation. This uses the thumbprint of the certificate that you used when authenticating to look up a principal that it should be mapped to. Or rather, more accurately, it uses a field named ‘kid’ in the JWT token. This field is usually set to be equal to the thumbprint of the certificate, but is not required to be.
If there is only one mapping table entry for the certificate, then the mapping is normally defined automatically and so in the example above, the principal (Darth Vader) was automatically determined.
In some cases, you may have multiple mapping table entries. In that scenario, you may want to specify a specific principal that you would like to be mapped to. If the mapping table entries permit this for the specified certificate, then the token you receive back will be for that specified principal.
You specify a principal by using the optional -Principal parameter in the set-tachyonserver cmdlet.
If you authenticate non-interactively using a platform token, then you are always mapped to the fixed principal, PlatformToken.
Retrieving a platform token
You can also retrieve a platform token (but without causing the PS toolkit to use it for authentication internally). To do this, you use the get-tachyonplatformtoken cmdlet.
In the example, we use the Corellian certificate.
Note
This works because the testbed platform we are connecting to was configured to use this certificate to sign platform tokens. Normally this would NOT be the case. A completely separate certificate is normally used to sign and verify platform tokens. Customers are not given a copy of this certificate, so in a production environment you would not be able to request a platform token externally as in the example here.
Of course, if an administrator was running this cmdlet on a machine which DID have access to the platform signing token, then they COULD request a platform token. However, their account would have to be configured to permit private key access to that certificate, of course.
Note that the type property of this token is 2, indicating that it is a platform token. It still maps to a principal, TachyonPlatform, which will have been given appropriate rights in Tachyon RBAC.