Transcript
[ Music ]
>> Welcome to session 508,
Getting and Using a MapKit JS
Key.
I'm Eric Gelinas from the MapKit
JS team.
In this video, we will learn how
MapKit JS authorization works,
create a MapKit JS key, create
an authorization token, and in
the end we'll make a map.
Let's dive into how
authorization works in MapKit
JS.
Anything you host on the web,
including MapKit JS is in plain
text.
One of the great things about
the web is the ability to learn
techniques from others simply by
viewing source.
Just open the web inspector and
see how it's done.
See a map you like?
View its source, see how it
works.
It's certainly how I learned.
Unfortunately, that sometimes
means that your API
authorization credentials can
get copied and used by mistake
without your permission and that
unauthorized use can count
against your usage limits.
Once the limit is reached, your
site may no longer be able to
display maps.
The MapKit JS authorization
system is designed to give you
more control over how your
credentials are used.
You can set a time when access
should expire and restrict
access to a specific domain.
It's the web and others will
still be able to view course and
poke around in the web
inspector, but if somebody ends
up with your credentials for any
reason, there will be limits on
how they can use it.
Let's discuss how MapKit JS
authorization works at a high
level.
Once you have a MapKit JS key,
you'll save it somewhere safe.
This will never be shared over
the web.
Instead, you'll create tokens
with restrictions and signed
with your key.
This token is what you will use
to authorize with the MapKit JS
API.
So, let's see how creating a
MapKit JS key works.
A MapKit JS key is your
credential to use with the
MapKit JS API.
This is a one-time set-up.
Here's how.
Create a maps identifier.
Create a MapKit JS key and
associate it what that
identifier.
And download your key and save
it to a save place.
Before we start, head over to
developer.apple.com/account and
log in.
From there, click on
Certificates, IDs, and Profiles
in the left-hand menu.
Our first step is to create a
maps identifier.
This identifies your project in
the Apple Developer website, but
it also serves to track usage
limits.
You may want to create different
identifiers for production and
development environments.
To create a maps identifier,
select Maps IDs from the menu.
Click the + button in the upper
right.
Give this identifier a
description.
The description should be the
name of your website as it will
appear to users.
Give this identifier a unique
ID.
We recommend using reverse
domain style for this ID and it
will need to start with the
string maps.
For example,
maps.com.yourdomainname.yourapp.
Now we'll create a MapKit JS
key.
This key is a secret shared
between you and Apple and should
never be stored in front end
code, checked into source
control, or shared with others.
First, click on All under the
Keys subheading in the left-hand
menu.
Then, click the + icon in the
header.
Then, give this new key a name.
Then check the MapKit JS
checkbox.
Then, click the Configure
button.
Now that you've created a new
key, we can associate it with
the maps identifier you created
earlier from the maps drop-down
menu.
Maps identifiers can only be
associated with one key at a
time.
When you've selected your maps
identifier, click Continue.
Finally, review your changes
when prompted and click Confirm.
Your key is now ready to
download.
Click the Download button to
save your auth key file to your
computer.
You can only download this file
once, so keep it in a safe
place.
If you do lose it, you'll need
to create a new key and then
revoke the old key.
When downloaded, your auth key
file will look something like
this.
As I said before, this key is
meant to be a secret between you
and Apple.
This is the only time you'll be
able to download your auth key
file.
We recommend you quickly save it
somewhere safe.
If you ever lose your key or it
is compromised, you can always
come back to the Apple Developer
website to revoke it and create
a new key.
You just created a MapKit JS
key.
Now we will create authorization
tokens which can be used to
authorize MapKit JS over the
web.
Tokens are created containing
your developer credentials and
are signed with your auth key
file.
Claims are added to this token,
which are used by Apple to
verify a client's authorization.
Let's dive deeper into how to
make authorization tokens.
MapKit JS authorization tokens
are based on JSON Web Tokens RFC
7519, or JWT for short.
This is an industry standard
designed to specifically
transmit authorization claims
over the web.
You can find more information on
this standard at jwt.io.
There you will also find
libraries for signing JWT tokens
in most programming languages.
All JWT tokens are made of the
following three parts.
A header, a payload, and a
signature separated by periods
and each Base64 URL encoded,
making a token which can easily
be passed to a request header.
We have two recommended JWT
configurations for your
authorization token: short-lived
tokens and long-lived tokens.
Let's start with short-lived
tokens.
These authorization tokens offer
the most protection against
misuse by ensuring that
authorization tokens can't be
used for long if copied from
your source code.
This approach requires that you
provide a server endpoint to
respond to requests for MapKit
JS for new authorization tokens.
MapKit will refresh from this
endpoint any time it needs to
authorize throughout a user's
session.
First, the payload must contain
an ISS claim, which is your
Apple Developer Program ID.
You can find your Team ID in the
account section of the Apple
Developer website.
An IAT claim, which is when this
authorization token was issued
in seconds.
An EXP claim, which is when this
authorization token is meant to
expire in seconds.
For short-lived tokens, we
recommend 30 minutes.
And, finally, a claim of origin.
This can restrict browser access
by matching the origin header
string.
Though this claim is optional,
we recommend it be used for all
authorization tokens, especially
in production.
Second, the auth key file
contents which you downloaded
earlier.
This full file including white
space, header, and footer,
should be used to sign this
token.
See the documentation for your
JWT signing library for
instructions specific to your
programming language.
Finally, the header section of
the JWT token will contain a KID
claim, which is your MapKit JS
key ID.
Note that this is not the same
as your maps identifier.
A TYP claim, which should be the
string JWT to identify this is a
JWT-style token, and an ALG
claim, which is the hashing
algorithm to use.
This must be set to ES256, which
when passed to your JWT signing
library will output a JWT token
ready to be used by MapKit JS.
Since short-lived tokens may
expire before your user is done
with their session, your server
will need to provide an endpoint
for MapKit JS which will respond
to requests to new tokens.
Later, I'll show you how to make
MapKit JS aware of your
endpoint, but for now, here's an
example of an endpoint that I've
created as an express JS route.
This route simply returns a new
access token set to expire in
1800 seconds or 30 minutes every
time it's called.
Regardless of your token's
expiry, MapKit JS will call this
endpoint any time it needs to
authorize throughout a user's
active session.
Since your endpoint needs to
return a new token every time
it's called, you'll need to let
browsers know not to cache.
You can do this by setting cache
control headers.
If set up correctly, you should
have a route on your server
which returns a token looking
something like this.
A long-lived token is different.
Its expiry is set much further
out.
You can use the same token for
many requests over a longer
period of time.
This type of token doesn't
require a server since the token
is not likely to expire during a
user's session.
For that reason, it can be
easily used on static websites
or in development environments.
You can sync expiration and
renewal of this token with your
release cycle.
We strongly recommend that you
attach an origin claim to
long-lived tokens.
Let's see how this is done.
In this example, we set
long-lived tokens to expire in
six months.
As I said before, you can tailor
this to your application's
needs.
For example, if your team has a
two-week release cycle, you can
set your expectation to sync
with that or even add a couple
weeks as a buffer.
Setting the origin claim is
always recommended, but
especially on tokens with long
expiry.
This is your strongest defense
against misuse of your
credentials.
Now with this token handy, we're
ready to make a map.
The simplest example of this is
to create an HTML page,
including a script tag linking
to MapKit JS on the Apple CDN.
Remember when I said that I
would show you how to make
MapKit JS aware of your token
endpoint?
That happens when you provide a
callback function when you
initialize MapKit JS.
For short-lived tokens, MapKit
JS will fetch new tokens as
needed throughout an active
user's session.
Note that when MapKit JS invokes
your callback function, it'll
pass it a function, which for
this example we're calling done.
Call this function with your new
token to allow MapKit JS to
proceed with the authorization
process.
If you're using long-lived
tokens, simply call the done
function immediately in the body
of the authorization callback
function.
MapKit JS will use the same
long-lived token any time it
needs to refresh its
authorization.
Finally, set a map container and
center for your map.
Now, let's start our server and
see this all in action.
If everything is set up
correctly, your browser should
display a map.
If you're using short-lived
tokens in the web inspector, you
should see a server endpoint
being called, returning an
authorization token.
Now that MapKit JS has its
authorization, it'll do the
rest.
MapKit JS will request from your
route whenever it needs a new
token.
So now you know how MapKit JS
authorization works.
You know how to create a MapKit
JS key, create an authorization
token, as well as how to make a
map initialized with your new
token.
Remember, get your MapKit JS key
and store it in a safe place.
Only send authorization tokens
over the web.
If a key becomes compromised,
revoke it on the Apple Developer
website as soon as you've
created and updated your website
with a replacement.
For more information, visit
developer.apple.com/wwdc18/508.
Have a look at our session,
Introducing MapKit JS, in the
Executive Ballroom on Tuesday at
5:00 PM.
Thank you.