[MUSIC].
>> Hey everybody. I'm Brian.
I wanted to talk to you today about a new way of
connecting Keyless Cosmos Connections.
But before we talk about the new way,
let's talk about how maybe you're already connecting Cosmos today.
Let's jump over into some code and take a look.
This is just a simple little function app I have.
It could have been a web app or
any other code where you want to interact with
Cosmos and you're likely using
the Cosmos SDK and this Cosmos client class.
The way this works, the most common way to use it is you
need to provide it two pieces of information.
You've provided the URL for
the endpoint of the Cosmos DB that you're talking to,
and the key for us to access the client or to access the cosmos.
You can provide these many ways,
you can have these maybe their app settings.
In my case, I've got them stored in Key Vault.
Key Vault is good for storing secrets and secure stuff,
so I've got my cosmos key in there just to make things easy.
If we take a quick look at the database,
we can see where this is coming from.
I'll dive in here to my Cosmos DB.
The first thing you can see is here's that URL,
that's the first parameter.
Then the second parameter is the key.
In my case, it's this rkmw key.
Those are two pieces of information we're providing to it.
While we're in here real quick, I'll just show you,
this is a successful database of a little bit of data in here.
We can see later that we're getting the right results.
It's just got three items
in here that well see later when we query.
If I hop over to the Key Vault,
that was the other half of this,
I've got my two secrets in here;
the URL and then the key and we can see the key is in
fact that same value rk and
w that I saw in the cosmos instance itself.
Those are both being ripped from keyboard and being passed
into this Cosmos client instance.
Then the ACK we'll take those and use those credentials
when I'm querying against my database to provide access.
If we look at I've to get this function app deployed,
if I take a look at it here it is
n. Here we can see they read my three records every time database.
Pretty simple, but it just shows that I was able to use
the key to access the database and get my data.
That's great how that works.
It's pretty good, but there's
a few things that we can improve on about it.
A couple of things to note here are
although I have the key in Key Vault,
that means that it's stored in another place now.
The key itself comes from Cosmos DB but
I've also got a separate copy of it in Key Vault.
That's one more secret I have
to manage and one more thing I have to worry about.
Also, it makes rotating the key a little bit more complicated.
If I wanted to rotate my Cosmos DB key,
I would actually have to do several steps.
I would come into my Cosmos DB.
I'm currently using the primary key,
so in order to do this without interrupting my service too much,
I would have to rotate the secondary key,
generate a new version, and then copy that into my Key Vault,
and restart my app in my case
because I'm only reading the secret at startup time.
Then rotate the primary key and take that value,
copy that in the Key Vault and restart my app again and then I
would be up and running on the new rotated key.
That's several steps.
It's hard to automate that could provide room
for human error and also a little bit of downtime in there.
I have to restart my app a couple of times.
That's not perfect. But there is ways we can improve on this.
In fact, if you jump into the docs,
you can see that it does talk about a way to
use manage identity to connect to your Cosmos DB.
But if you scroll down here a bit and
see what it's actually doing.
In the mid of it, you can see
it's calling this management.azure.com.
These are the rest APIs that power all of Azure.
What it's doing is it's calling this API and then it's
calling into the Cosmos DB provider and then
it's calling that list key's function.
What that does is it gets the key directly from the database.
But if you look down here,
it's the same Cosmos client that we were talking about before,
still passing at the endpoint.
Then instead of passing the key from key rather app settings,
it's just getting the key directly from that rest API call.
You're not really accessing it with the manager identity,
you're not avoiding use of the key,
you're just getting the key directly from the database.
You did remove key vault,
it took one thing out of the equation, which is an improvement,
but you're still essentially using the same technique,
just getting the key from a different spot.
That does provide some improvements though.
For example, the key rotation
that was more complicated with key vault is a little easier now.
When this code runs, this call will get
the key directly from the database.
Even if you've rotated, you'll get the current one and it'll
pass that to this instance so you have the right one.
That is a little better. But it
still is using the key and we want to avoid
using the keys and avoid as many secrets as
possible so we're going
to see if we can do a little better than that.
Let's recap around.
When we talked about so far,
in order to connect the Cosmos at all, you have to know the key.
Things like Key Vault is secure,
but storing your key in there is just one more thing to
manage and make things like key rotation
complicated because you have to do
that five step dance to
get the key rotated and updated and restarted.
Even if you use the rest API approach to avoid some of that,
you're still using the key.
The important part there is that the keys are all or nothing.
If your key leaks out into the wild and someone has it,
then any color can use it.
There's no any more fine grained control
and that is just if you have a secret,
you can access the database.
We want to try to improve upon that.
In fact, if you go back to the same document of the official docs,
you can see up at the top,
there's actually been updated to say that there's an even newer,
better way to do this now.
It's in this nice little green box
and it's called data plane rule based access control.
When you click into it, it's very thorough and it's got
all kinds of information about how it
works and all the operations you can do.
But it's actually quite simple to actually implement in real life.
I'm going to show how to do that real quick.
In our function app before we were
providing the endpoint and the key,
but if you look at this, the signatures here,
you can see we're using the one
that takes an off key or research token.
But there's actually another overload
that takes a token credential.
The easiest way to provide
a token credential is move Azure credential.
Default Azure credential is nice, because it's smart.
When you're running this locally, you're
doing development on your local machine,
it will use the credentials
that you're logged individual studio with or your
Azure CLI so I log in with
my account and that will use that locally.
But when I do play this code to Azure,
it will automatically use
the manage identity of the service because I don't have to have
any if statement the environment
where it will just do the right thing
in the different environments.
You can see here, we're still telling it where the Cosmos DB is,
but instead of a key,
we're just providing this credential.
We don't even have to use the key
anymore. We can take a look at that.
This is also deployed already.
Before we had a query that was using the key for
access and then we use the one that's using
the keyless access, isn't here.
This is actually expected because you can see here it says
the request is blocked because the principal will be 471,
etc, it does not have the required permissions.
Unlike key base access,
we're simply having the key,
provided to you the necessary credentials. This is role-based.
Now we've been abled role-based access,
but we didn't actually grant any permissions to anyone.
I need to grant access to my function app in order to be able to
call into Cosmos DB using this approach.
I'm going to go ahead and grab this ID
and then show how to do that.
This is important ways to note that this is all fairly
new and so you can't do a lot of this via the portal UI.
Normally you would go on to the portal UI and
click around and be able to configure some of this.
But at the moment, you have to do this
using command line tool so you can use
Azure UI or PowerShell arm templates a few different ways,
but you can't do it visually in the portal quite yet.
Let's come back over here.
I'm going to go ahead and kick this off and then
I'll come back here and explain what it's doing while it runs.
>> This is the new commands that are available to enable this.
There's this Cosmos DB sequel role assignment in Azure Sea Lion.
There's an equivalent for PowerShell.
What this is doing is you need to give it
a few things to tell it where Cosmos DB is.
You need to give it the subscription,
the resource group name and
the name of the Cosmos DB you're connecting to.
Then the important bits are who are you giving access to?
That's this b47F that we just saw didn't have access.
I want to grab my function and add access.
The second important part is the role definition.
There are two different roles.
You can use the 0001 role which is read only,
or the 0002 role which is read and write.
These are not rules you might be familiar with in Azure.
If you log into the portal and you're a contributor and
you've got access to do certain things in the forum,
those are called management plane access roles.
Those give you access to create resources and manage resources.
This is what's called a data plane access role.
You can see this is not a unique
good or anything, it's just a bunch of zeros.
This is specific to Cosmos DB,
and this is just for accessing the data within the instance
versus the management playing roles that
are for managing the instance itself.
It's important to note the difference between
data plane access and management plane access.
Hopefully this ran by now and we'll see.
Not super important here other than to see that it ran.
When it's done it dumps out some information,
essentially telling me that it did go ahead and
grant this rule to that principle.
If we switch back now to our test,
we should see now that
previously when we were blocked because
we did not have the required RBAC permissions,
now we're using the default Azure credential
and we have granted access to this principle.
We should now be able to access our data and we can see,
in fact, we are and there's those three records from the database.
That shows that we can access it,
just like before and didn't change
any code in how I access the database.
As far as running the query or anything just in the way that I
constructed the Cosmos client
and the way the credentials were provided,
and you can see that the key base way it still works as before.
They both return the same data now.
But if we go back to our code we can
see that we're not even using the key anymore.
We're using this default Azure credential
and so the keys not even required.
Not only can we not use the key,
we can also set up our Cosmos DB to
not even allow the key to be used at all,
which will make us even more secure.
Again, you can't do this via the UI,
but we'll go ahead and do this one.
You can do this via an ARM template.
Here's an example of the stripped down ARM template.
This is the Cosmos DB resource and then down here,
the important property is this one, disableLocalAuth.
If I set that to true,
that's going to tell Cosmos DB to not allow,
they call it LocalAuth, but that's essentially key based auth.
I'm going to go ahead and run that and then
I'll come back and go into a little more detail now.
That's my home screen.
While that runs I'll talk a little bit more
about since this isn't available via the portal,
how you can tell what's going on.
So if you go into your Cosmos DB and you scroll all the way down
to the bottom and you export template this will generate
an ARM template that represents
what's currently deployed in Azure.
There's a couple of things you can see in here.
So here is the Cosmos DB instance itself and that
property we were just talking
about is in here disableLocalAuth is still set to false.
Our ARM template deployment is still running, it hasn't finished.
This is still set to false
and then if you scroll down a little more,
you can see a few other things in here.
Here's those two role definitions.
Here's the 001 the reader role,
and here's the 002 the read write role.
Then below that, a little bit more
are the actual role assignments.
If you get down here a little bit further,
you can see here's the one we granted.
Here's we granted the rewrite 002 role to
my function app which was that b47F principal ID.
Although you can't manage
just the point and click UI in the portal,
you can indirectly see that it's working
properly by exporting your ARM template
and seeing the properties in there.
Hopefully by now we can see that this ARM template has completed,
it succeeded so that's great.
We just hop back in here and just refresh this ARM template.
Well, it should see now that I disabled
LocalAuth has now been changed.
In fact it has and now it's set to true.
That means that we've told Cosmos DB to
not allow key based access at all.
What that should mean is when we go here to
our this created which was the keyless,
our back base access.
What it should mean here is that when you go back to here this was
our key based access that we can no longer access it.
The key here is this as local authorization is
disabled and you need to use an AAD token to authorize or request.
This key based access,
we still have the right key,
but the Cosmos DB itself is preventing it from accessing it.
Even if a key leaked out into the wild no one can use it.
It's effectively unusable at this point.
Let's talk about where that brings us so we talked
about why using a key might be problematic.
Now we talk about why using keyless might be better.
You don't need to store your key in
Key Vault or in your app settings at all anymore.
It's one of my secret to manage
that key rotation complexity is not only easier,
it's completely removed, there's no key to even rotate,
so you don't have to even worry about it.
Like we saw, you can disable key access entirely so
that even if your key did leak and some attacker got it,
it's useless to them because you're not even
allowing access via key at all anyway,
only via role based access.
Then the important part of all that is that that also gives you
more fine grained control so you can grant access to one app,
you might give them re-access,
you might give another app access for read and write.
You might revoke it for someone
else because it's role
based you get a lot more fine grained control,
whereas the key based approaches.
If you have the key you can access the database.
This gives you a lot more control.
There are some caveats to all of
this one of which is I mentioned a few times,
you can't manage this in the portal.
I did show you how you can export
the ARM template and see the effect of this.
But in order to set this stuff up,
you need to use command line based tool.
On the next slide I've got some links to
resources there's Azure CLI commands,
there's PowerShell commands that
you can use to do this stuff In the meantime.
There is a plan to add this to the portal so you can use it in
the UI but for today you need to use the command line tools.
Another important point to call out is that
the data explorer in the Azure portal
requires key based access to function properly.
What that means is if you hop into
your Cosmos DB and you go into the data explorer earlier we
saw here this is where we saw
the three records and I tried to view
them and now I get this red bang and this we saw earlier,
local authorization is disabled.
The data explorer in the portal itself uses
key based access to function properly and so when it's disabled,
it doesn't work anymore.
That's not great but there is a workaround.
In fact, the docs that we were reading just a
moment ago do give us a tip down
here at the bottom that says
that you can use the Cosmos DB Data Explorer instead.
It's right down here a little bit further.
This talks about how the portal doesn't support it yet,
but you can use that as your Cosmos DB Explorer instead.
It does support our back keyless connection.
You can still view your data and interact with it.
You just can't do it right in the portal which isn't perfect,
but we'll get there.
Then the last one to call out as far as caveats
is that the Cosmos emulator also doesn't support our back.
Because the emulator is a standalone thing.
It doesn't know anything about Azure or accounts or roles.
It still requires a key.
It has a well-known key that's published with the docs that you
use to connect to it, and you need to keep doing that.
If you're using the emulator for
your local development or maybe you're
using integration tests or your CI pipeline,
you still need to use that one key.
You may have to have in your code some detection environment.
If you're running in one of these test environments,
use the one on key.
Otherwise you can use the default Azure credential
and connect with a keyless approach.
Here's a couple of things we were talking about.
The first one is that document that goes into
more depth about all the different roles,
the role assignments, what each of
the permissions that each grants and how to run it all.
The second two here, talk about
the Azure CLI commands and
the PowerShell commands that we were using.
There's documentation they're all fully documented.
Here's the Azure CLI ones.
I was using the Create Command earlier and giving it
the resource group and
subscription ID and the principle that I wanted to grant it.
You can also delete lists,
show there's a few other things you can do.
Then there's also the same corresponding commands for PowerShell.
You can do all the same stuff with
granting and listing all the role definitions.
That's how you can do it. In the meantime,
we need to use command line tools until the portal is updated.
Then the last one link here
talks about manager identity in general the concept,
we didn't go deep on manager identity,
but that's the basis for how all this our back stuff works is
in order to grant a role based access to someone,
we need to know who that someone is.
In my case, it was a function app, could have been a VM,
web app anything manage
identities is the concept that underpins all of that.
We can tell with who is
this Azure service that I want to grant access to?
We talked a little bit about how you connect today,
how you can use this new feature to connect and remove secrets.
Now you'll know how to use
keyless Cosmos connections can connect to your database as well.
That's it. Thanks everybody. Bye.