Overview
In this video, Ben Arent walks you through:
- Okta Setup
- Configuring Okta
- Setting up Okta Groups
- tctl create okta.yaml
- Assigning groups in Okta
- SSO debugging
Setting Up Okta SSO with Teleport
Ben: Hi. I'm Ben from Teleport, and today, I'll be walking through how you can use Okta to log in to Teleport. By using Okta, you have a central identity provider that can provide access to your applications, databases, and Kubernetes clusters using the role-based access control groups that you have in your identity provider.
Ben: Okta setup
There's a few things you need to do to set up. You need an Okta account. I've just created a brand new Okta account, just signed up on the 30-day trial, and that's about it. Okay. Let's dive in. Oh, you also need the commercial edition of Teleport. So we're going to enable a SAML authentication. We can do this afterwards.
Configuring Okta
Ben: Let's first configure Okta. So we're going to come in here and just create a new application. It's a SAML 2.0, and it's a web. This is going to be called Teleport. You can add a logo just to make it more easy to identify later, but we're going to skip this for now. And then now we're going to configure the SAML, so the single sign-on URL. This is going to be this URL here, and so in my case, I have my cluster running on “six-one-sso”, so let me update this, and then you also add the port. Audience URI — this is going to get you all of your audience information. It's the same thing; it's webapi/saml/acs. The default relay staten— keep this empty. And the next thing we do is Name ID. We pick email. Application username is the one that's going to show up in Teleport. I think we recommend also using Okta username. And Create and update.
Ben: Okay. The next thing we want to do is we're going to go down to Username Attributes. Let's configure this to username, and Name format is unspecified, and then the Value is going to be user.login. And next up, we're going to add a Group Attribute. This is going to link Okta groups to our groups in Teleport.
Setting up Okta Groups
Ben: And so the group, we just select Groups, and then the regex is a dot and then a star. It's a dot and a star. So Groups, Starts with dot, star. I think everything is now set up, and we can go Next. And then, "Are you a customer or partner?" I am just adding an internal app. Skip this information, and now we have the Setup Instructions. And then, we have information on what are the conditions and what you can do with the Okta integration. Okay. So we will also need to create the groups in Okta, so let's come back here into my Directory. I just have myself right now. Let's create a couple of groups. For this setup, we have two groups, one called “okta-dev”, and I'm going to create another group, “okta-admin”. So then, if I come in here, another thing we need to do is also just add myself to this group. Actually, myself to both groups. And this is how you would manage — you ask your team to use Teleport.
Ben: Okay. So we've added the groups, and then next up, we need to download the information. So let's go back to Okta. We have the one application, and the information is on Single Sign On, key setup instructions. And we can just download this, or we can just copy and paste this. So let's go to our next step. So we're going to create the connector. Let's put this into a scratch pad. So let's just walk through this. So we're going to create a new SAML connector. We're going to call this Okta. We're going to display it as Okta, so it'll say, "Login with Okta." This is going to be the cluster URL that we've already predefined, which will be, in my case — and then 443. We have the two groups. I'm going to check. We have a admin role, and I'm actually going to change this to "access," which is two built-in roles that we have. Actually, make this "editor" and "access." And then lastly, we have this, which is kind of interesting. It's a XML document in yaml, but this is the content, this information here, so copy this. And there's a few things to do. We'll type here, and we just copy this and paste it. And then another important thing is just to indent everything. We just highlight all of this and just make sure the indentation is correct, so two tabs, and then this should be fine.
Ben: Okay. So now I'm going to log in to my Teleport host here and create okta.yaml, the same file that we were just working with. And then, we use tctl, which is our administrative tool. And so, just before we go too deep, you can see here I have the Teleport cluster. You can't log in yet with anything, and so we're going to now use tctl to create this Okta provider.
tctl create okta.yaml
Ben: And it is Create, and then it's okta.yaml, and it says 'okta' has been created. So if we reload the cluster, we can now see that we have a sign into Teleport using Okta. So it says, "You can't access because you are not assigned this app in Okta." So this should be an easy fix. We've just got to check the Assignments, and we don't have any People or Groups.
Assigning groups in Okta
Ben: So we need to come back in here and assign the two groups that we had, okta-admin and okta-dev. Now let's go back, sign in again, and it says, "Unable to process callback." So let's start Teleport in a debug mode and try and figure out what's happening.
SSO debugging
Ben: So we're starting Teleport now with -d to start our debug logs to see what's happening. It's a very helpful tool when you're just getting started. We'll try and debug what's happening. So try and log in again, and you can see that we had a SAML error, "Unable to map attributes to role for the connector okta." So let's just review our connector again. Okay. So I've found the issue. One of the issues is my groups aren't getting populated because I didn't change this filter from "Starts with" to "Matches regex," and then this will be able to obtain the groups. So let's just update this, save it, refresh. Let's go back, and now we're logged in using Okta. So that finishes the end of how to set up.
Conclusion
Ben: As I mentioned here, you've got to make sure that "Matches regex," but that finishes how to connect Okta to Teleport. There's a few other things. You might want to look in here. So you can also use external.username and traits, so you might want to use such things as, "Only allow logins if they have that login in their Okta group." If you have any questions, please leave a comment below. Thank you.
Key links:
Join The Community
