API authentication with Adobe Experience Manager as a Cloud Service

Transcript

Okay, well, welcome everybody to this session. This is the API authentication with AM as a cloud service. And more specifically, it’s server to server API authentication. My name is Brian Chickleson. I’m a product manager and I am joined by my colleague from engineering, Timothy Merritt. I mentioned this just a couple of minutes before, but in terms of agenda, I’m going to give the use cases, the use case for this, maybe some data flows. Timothy is going to continue with a nice demo to really make this concrete and we’ll take some questions. And as I mentioned, we’ll be able to go to the community forum and there’s a link to that already in the chat after the session. And that will give us a chance to just talk a little bit more about this topic. Okay, well, what is our use case? We’re really talking about authenticated API calls between a server and AM. And when I say a server, I mean examples like the PIM systems, so this might be in the commerce space, so product information management system, pushing metadata, could be inventory metadata into AM. So you see those authenticated API calls are being sent in and note that this is on behalf of a system user, right? A system user also sometimes called a technical user or a service user. Another example of a use case is a workflow product like Workfront pushing states into AM. This might be the state of an asset, the state of content, right? So like really good for integration type of use cases. We do have another flavor and that is maybe remote other devices such as a native mobile app might have a browser that’s running a single page application in SBA. In this case, they’re going to make this authentic API call to a server, right? Because the mobile app obviously isn’t a server, so it’s going to make a call to a server and that’s where that server will then kind of make that call over to AM, that authenticated API call on behalf of the system user. Let’s take a look at a quick flow, data flow. So you have this non-AM server that I mentioned, it might be where Workfront or whatever your integration is running, and that’s going to pass a JWT token over to Adobe’s IMS, that’s the identity management system, and that gets exchanged for an access token. Once you have that access token, it’s pretty simple, you send it over with the HTTP call to AM as a cloud service and you get the response. But I kind of just glossed over something, right? There’s an assumption here, how do you get that JWT token? And this is kind of what this feature is about. So let me introduce you, if you’re not familiar with it already, to the AM as a cloud service developer console. If you’ve used AM as a cloud service, you might be familiar with the developer console for generating status dumps, really helpful to get all sorts of information when you want to debug what’s happening in a cloud environment. And so there’s this new integrations tab, and the integrations tab has a couple of buttons, and we’ll go through each of them, but right now I want to call your attention to the get service credentials button. And so the IMS org admin, so not just any user role, but an IMS org admin, will be able to download the service credentials, it’ll click that button, and then they’ll install them on a server, treating them as a secret. And then an application, your application will basically read in those credentials, will give you some code to do that, you’ll see it when Timothy does his demo, and you’ll use that, the script that we give you, the program we give you will allow you to construct that JWT token that you can pass over to IMS. So looking at that flow again, and kind of taking it back a couple of levels, a couple of steps, you have this AM developer console, where the IMS org admin can download that, I click the button, download the credentials, install them, treating them as a secret, and then the server will be able to use that to construct the JWT, again, passing it over to IMS, getting the access token back, and being able to use that short lived access token to send over on HTTP API calls over to AM as a cloud service, and you get the response. Pretty simple. So before Tim provides a demo to make this really concrete, I just wanted to describe that other button that you saw. If you want to do a quick and dirty development, you’re not at this point interested in doing the JWT exchange, you just want that access token. So this flow is really just the developer console, the user, it doesn’t have to be the IMS org admin, being able to download that token, passing it over to the AM as a cloud service with your HTTP API call, and get the response back. Just looking at the developer console again, that’s this button over here, the get local development token button, and that will give you that token. Okay. Well, very good. And now with that kind of context, now we’re ready for the more exciting part of the presentation. So Tim, why don’t you go and take it away for a demo. Thanks Brian. And here we go. In this demo, I’ll show you how to leverage the server to server authentication flow to authenticate against an AM as a cloud service environment. And this authentication flow has been released recently actually. So the demo will be live and performed against a standard AM environment and a up to date one. So the use case in this demo, it’s a third party workflow engine that needs to integrate with AM to change the publication date of a standard AM asset. The workflow needs to authenticate against the AM author tier, but it runs in the background. So in this context, it doesn’t have access to an end user session. So to solve this issue, the workflow will authenticate as a technical account. And we can think of a technical account as like a standard user, but one that is managed exclusively without human interaction. For instance, a technical account doesn’t have a password, so it doesn’t have to comply with ever-changing password policies. It doesn’t have to accept also ever-changing terms of use and so on. So regarding the flow, the flow will be the following. The workflow engine will use the server to server exchange to obtain access tokens for the technical account. Then it will pass it as a beer token via the authorization header in every request made to AM. AM will validate the access token and authenticate the technical account in the request. And to obtain an access token, the workflow will create a JWT token first, and it will include some claims that correspond to the technical account, sign the token, and exchange it with IMS for an access token. So before doing this flow, we need some setup, as Brian mentioned earlier, and we’ll go through it in the developer console. So what you should see now is the developer console already connected to my environment where we will run the demo. And as Brian said, we have added an integration tab, and I won’t go into the details for the local development token because we will focus mainly on the service credential use case in this example. So when we click on the Get Service Credentials, what happens in the back is that AM will create a technical account and an integration for it. Then it will open a new window and display all the credentials that have been generated and allow you to download them. So I won’t click on this button today because it would disclose the secrets, and I want to hopefully finish this live demo before the technical account gets hacked. So instead, what I’m going to do is to show you a redacted sample that we provided in our official documentation, and we will go through what it contains. So it’s a JSON document, and the first thing we can see here is the technical account identity. So a technical account has an email, it has an ID here, and it belongs to an AMS organization. Underneath it, we can see a property, a private key, and that’s the private key that our workflow engine will use to sign the JWT tokens before sending them to IMS. And then we have a public key property, and IMS already has this property. When we create the integration, we send this public key to IMS, and IMS will actually use this public key to validate the signature of the JWT tokens. Then we have the endpoint, the IMS endpoint that we will need to invoke. And underneath it, we also have a bunch of metascopes, and the metascopes, they correspond to all the privileges that can be granted in the access token. So a JWT token will claim either all of those metascopes or a subset of them, and they will be granted in return. And then we have a client ID and a client secret. So to access, to invoke the JWT exchange API from IMS, we actually need a client like that with a secret. And what’s important to note here is that there is no access token in this config file. It’s only a bunch of credentials that allow you to obtain access tokens. While the access tokens, like the one obtainable through the local development button, is valid for one day, those credentials, this set of credentials is valid for one year, so you can download it once per year. And that’s it for the console part. There is another part that needs to be completed for the setup, and it’s about granting more privileges to the technical account on AM. The use case we want to cover requires writing a property on an asset, and that requires the privileges corresponding to the content author’s group. So to grant those privileges to the technical account, we can do it actually using the standard security UI. So you should see now the author UI for the environment that we will use for the demo, and I’m going to navigate in the security and then users UI, and then search for my technical account. Tim, you might want to just increase the font size a little bit, just as a little blurry, if you can. Otherwise, we’ll make you. Yeah. Okay, thank you, Brian. So here it is in the groups. I’m going to search for authors, and I have content authors, and then I’m going to save this and close, and here we go. So at this point, we have a technical account. It has the privileges we need, and that completes the setup, actually. Then let’s have a look at the assets that we will update, and it’s this one here. If I get more details for it, and then the properties. This is the property that we are actually going to update just here. The scheduled activation, the on-time one, and it already has a value, but the workflow and shine, and we will see it later, will update this value asynchronously. That’s all for the asset. The last part that we want to review before running the demo is the workflow and shine. For this demo, the workflow and shine is actually a small Node.js app. It’s only 100 lines of code, and we will go through the code together because it’s pretty small. The first thing this app does is take three options, three parameters. The first parameter is the author URL. The second parameter is the path of the asset we want to update. The last parameter is the credentials file that is downloaded directly from the Dev console. This Node.js app supports both the service credentials config file or the local development token from the Dev console. And then the code just parses the JSON config, and then it’s going to invoke every 30 seconds the update on time, so it runs the workflow every 30 seconds. Let’s see what this method does. It’s going to update the on-time property of the asset using the Apache Slink post servlet. And to do this, the first thing is to get an access token here. We will look at the implementation later, but for now, let’s focus on this context here where we have obtained an access token here. So the first thing we do is we create a form, we set the on-time property with the current date, and then we issue a post request, and here is the interesting part. We pass the access token as a beer token for the authorization header. Then the script simply logs either the success or the failure for the call, and that’s kind of it. Let’s see at the get access token implementation. So it’s here, and as I said earlier, the small app supports the two config files from the Dev console, and it decides here which branch it has to go to. So if the config contains an access token, it assumes it’s the local development access token config file, and it will just return it. If it doesn’t contain an access token, it will go to the access token exchange. And here is the implementation of the access token exchange. The beefy part, let’s say, is actually quite simple because it’s about exchanging the config file for an access token, and that happens here. To do the actual exchange, we leverage a library that Adobe published. It’s called the AM Cloud Service API Client Library. So it’s open source, and it’s available on GitHub in the Adobe organization. So we simply have to invoke this method, pass the config as a parameter, and then we get a response, and the response contains an access token, and we can just return it. There is one thread here, which is about caching. So access tokens are valid for one day, and after that, they expire. So during this validity time, this one-day validity time, it’s a very good idea, actually, to reuse those access tokens. And that’s what we are doing with this small cache here. The cache has a time-based retention mechanism, and we use the expiration time minus a small 5% leeway to make sure we don’t use expired access tokens. We cache it for almost one day, essentially. And that’s kind of it. Why is it important to cache? It’s important to reduce the latency when invoking APIs provided by AM because it saves the round trip with IMS to do the access token exchange. The second reason is that at some load, IMS will probably throttle requests for the client that you use to do the exchange. So caching is an essential and very good way to reduce the load and save and reduce the latency for your application. So that’s kind of it for the source code. We have covered the implementation, and now we can try to run it. So you should see now my terminal, and I have cloned the Workflow Engine repository on my desktop, and inside of this repository, I have already downloaded the service credentials JSON file, which is here. And what I’m going to do is to invoke the workflow.js app using Node, and I pass the AM author URL here, the path of the asset we want to update, and we pass the service credentials JSON file. So let’s run the code and see what it does. So the client library that we use is going to log, by default at least, it’s going to log the content of the JWT token sent to IMS for the exchange, and it’s also going to log the interactions with the Exchange API. So we can see here that it’s a standard JWT token. It has three parts, the header, payload, and the signature. The signature has been produced with the private key that was downloaded from the Dev console, and the payload has the IMS organization that our technical account belongs to. The subject is actually the ID of our technical account, and then the audience are the bunch of metascopes that we want to claim. Then we see here that the library does a post request to the Exchange API and gets back a 200 with the access token in the response. Then we see that our workflow app logs successful updates of the on-time property with the current date for this asset. There is one important thing to note. There is only one exchange here that is logged here, and even though we made many updates, there are already three here, four now to the property, and the reason is caching, as we saw earlier. So now let’s see in the DOM if the change is effective or not. So this was the value before we started the workflow app, and now if I refresh the page… …we see that the value has been updated to the current time as expected. So that worked pretty well, and that’s it for the demo. If you are interested to run the demo on your own AM environment, it’s possible. The source code is available on GitHub, and we have included the coordinates of the repository as well as other links in the presentation slides. And with that, I am handing over to Brian to handle questions and to conclude the talk. Great. Thanks a lot, Tim. And we could maybe put those links in the community forum so that they’re kind of persisted there for people to take a look at on their own time. So let me just kind of share one more slide, the wrap-up slide. Okay. So, again, I put in the chat the public documentation, so that should have what you need. And, again, we’re going to put the demo code into the community forum. So with that, I’ll stop sharing and see if there’s any questions that have come up. I know David Gonzalez has been good enough to answer a couple of them, but let’s see. I think Peter asked, how long is an access token valid for? So I think, Timothy, you mentioned that it’s about a day, 24 hours or so, so that the time is not configurable. And, you know, is it possible to have access refresh token to the refresh access token? I don’t think so. So basically this is what we give you at the access token. Yeah. There’s a question about, is the token exchange library available in other languages like Java or C-sharp? So David responded, Timothy, tell me if you agree with this. I believe you agree with this, that, you know, maybe there are some code samples, and David provided a link to that, so you can kind of check out if there’s anything that meets your needs. Is this planned only for cloud service or AMS too? So this is for cloud service. That’s where the AM cloud service developer console is located. Timothy, do you have any thoughts on AMS? I mean, there’s other ways of doing this type of thing in AMS, right? AMS, which is for many of you are probably familiar, right? That’s the Adobe or AM managed services, so kind of a different offering of this. So Timothy, would you agree that there’s different ways of doing it for managed services? You wouldn’t basically need to take this particular approach. Obviously you can make API calls from a technical user, for example. Yeah, so I’m not aware if this flow is integrated and supported in AMS at this point, but conceptually it would be possible to port it there, but I’m not aware of the level of their offering at this point for AMS. Yeah, but it’s definitely through a different mechanism, right? So you wouldn’t use the developer console. Exactly. So the integration is lacking at this point, yeah. So Aheem asks a couple of questions here. Why would you run that code on a local machine? Okay, so I think that you would run it on a local machine because you’re just doing some testing. You want to see that things work. Obviously, when you’re in a production type of situation, you’re going to obviously want the server that’s doing whatever is connecting to the AM, but this is just for kind of development purposes. And a bonus question from Aheem, and that’s how would you authenticate local curl-like commands that trigger one-off or maintenance jobs? Timothy, do you have any thoughts on that again? How would you authenticate local curl-like commands that trigger one-off or maintenance jobs? So as long as the API is provided by Aheem, it’s quite straightforward to use this authentication mechanism using curl. You can pass headers in your curl command, and you would just set the authorization as the given access token. So that will work pretty easily with the local development access token that you can download from the Dev Console, but it’s a bit more involved to do the actual exchange, but it’s not far-fetched because it’s just about invoking the proper IMS APIs, but there is no such script available at the moment. We could extend our SDK to do it, but at this point, I think it’s not available. Okay, so I believe we’re going to be cut off from the session. We’ve reached the conclusion, so thanks, everybody, for attending. And again, I put in a link to the Community Forum where Timothy and I will move over after this. Hope you have a great rest of the day. Thanks, everyone. Thank you.