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.