So you followed along with our tutorial showing how to create your first Aras InnovatorEdge API, and now you're wondering "How do I connect as a user instead of an API key?" Well wonder no more!
This post walks through configuring user auth for an Edge API, helping you understand how it works, and validating your setup before diving into building an app. By the end, you'll be able to send an authorized request to your Edge API from Postman, logged in as an actual Innovator user, not an API key.
Why not use API keys?
API keys are fine for prototypes and single-owner tools. Once real users are involved, you want each person's actions to run as them in Innovator, with their permissions, their identity, and their access rules. Innovator's permission model does the work, so you don't have to write permission-specific code. A user who can only see certain Parts in Innovator sees exactly those Parts through your API once the auth is wired up correctly.
The user auth flow
Before diving into the configuration steps, let's look at what's happening during a user auth flow for an Edge API. When authenticating as an end user, there are four systems working together to ensure that the user only sees the data they have permission to access and that the requested data is allowed by the scope of the Edge API.
We've drawn up a basic sequence diagram to illustrate how it works and show the systems we need to configure.
- Client App: Postman in this case, but generally the client the user interacts with
- Aras CIAM: the identity provider issuing tokens so the client app can call Edge APIs via AMS
- AMS: the Edge API service, which validates requests and queries your Innovator instance
- Aras Innovator: where your users, data and permissions live
This might seem like a lot of steps for a simple API call, but this architecture is what makes Edge APIs more secure. The token received by the client app can only access the Edge API – no one can take that token and use it to directly query Aras Innovator. The separation of AMS and Innovator also enables admins to control the data and operations allowed in the scope of an Edge API. That means you can prevent apps from getting sensitive data without changing your users' permissions within the Aras Innovator client.
Configuring CIAM
There are three key steps to configure CIAM to work with your app and Edge API. Get started by navigating to https://iam.aras.cloud/ or click the Manage CIAM Access button under the Access tab of your API in AMS.
1. Register the API in CIAM and copy the audience ID
In CIAM, go to the APIs tab and add your API with a name and description. CIAM generates an Audience string for it once you click save in the dialog. That's the audience your tokens will be issued for, and it's one of the values Postman needs later.
Copy the Audience ID, then go back to the Edge Access tab and paste it into the Allowed Audience field. Save. That's the handshake that tells Edge to trust tokens issued for this audience. You should see the audience string reflected back in that field once it saves.
2. Register an Application in CIAM
Back in CIAM, go to the Applications tab and add an application.
The fields that matter, under Settings:
- Name: human-readable, your choice ("Postman - dev testing" works fine).
- Application URL: not load-bearing for this walkthrough; use a placeholder like http://localhost.
- Callback URLs: add https://oauth.pstmn.io/v1/callback, Postman's built-in redirect target for testing OAuth2 flows. (If you already have your future app's callback URL, add that too, comma-separated. You'll need it in the next post anyway.)
- Logout URLs: not required for this walkthrough.
- Allowed Web Origins: leave blank if you're only testing from Postman.
And under Advanced Settings:
- Authentication Method: set to None.
Under Roles & Permissions:
- Allowed APIs: select your API. If you skip this step, you may get a 401 Unauthorized error when testing your setup. CIAM needs to know which API(s) this application may access.
Under Access Rules:
- Click Add Access Rule and select the users and/or groups you want to access your application. We're not going to worry about roles for this use case, and I've opted out of sending notification emails about this new rule.
Now save the Application settings and close the dialog, then copy the Client ID and Client Secret CIAM generated for it.
3. Make sure each user exists in Innovator
This isn't a CIAM or AMS setting, but it's the step everybody forgets.
Every person who logs in through CIAM must also exist as a user inside the Innovator instance your Edge API is connected to, with a matching email address. CIAM issuing a valid token doesn't mean Innovator will do anything with it. No matching Innovator user means a successful login but empty or 403 responses from Edge. If you're not sure which Innovator instance your Edge API points at, check the Connect Instances tab on the Edge API page.
Setting up Postman
With the Edge and CIAM configuration done, you should have three values in hand: the CIAM auth url, plus the Client ID and Client Secret for the Application you just registered.
Open a request in Postman, go to the Authorization tab, and set Type to OAuth 2.0. Select Get New Access Token, choose Grant Type Authorization Code, and check Authorize using browser. That's what sends you through a real login page instead of an embedded webview, which matters if your CIAM tenant does anything beyond a plain username/password prompt.
Fill in:
- Callback URL: Postman defaults to https://oauth.pstmn.io/v1/callback, the same url you added to the Application's Callback URLs in CIAM.
- Auth URL: https://iam.aras.cloud/auth/authorize
- Access Token URL: https://aras-ext.us.auth0.com/oauth/token
- Client ID: your Client ID from CIAM's Applications tab.
- Client Secret: your Client Secret from the same place.
- Client Authentication: Send as Basic Auth header.
- Scope: openid profile email
Tip: When you include the optional "offline_access" scope, CIAM will provide the client app with a refresh token that can be used to get a new auth token when your current token expires. Postman will handle the refresh step for you automatically if you enable the Auto-refresh token setting shown in the screenshot above.
Now select Get New Access Token. A browser window opens, you log in as a real CIAM user (one you already granted API access to in step 3), and Postman gets handed back an access token.
Next, click Use Token in the Postman dialog. Postman will automatically add it to your request's Authorization header as a Bearer token.
Calling the Edge API
The auth is all set up, so now all you need to do is point the request URL at your Edge API's endpoint and send it. If you aren't sure what url to use in your request, you can find the Execution Endpoint for any entity by browsing your API's schema in AMS.
If everything's wired up correctly, a GET request will return data scoped to that user's Innovator permissions, not a flat 401 or 403.
Troubleshooting auth issues
Common issues
If you're able to get an auth token from CIAM logged in as a user but you're getting an error when using that token in a request to your Edge API, check these common causes:
- The user doesn't have an access rule granted on the app in CIAM (step 3).
- The user's email in CIAM doesn't match an existing Innovator user (step 4).
- The token is missing the necessary scopes to map the CIAM user and Innovator user ("Configuring Postman for the login"). You need to include the following scopes when requesting a token, otherwise you'll get a 500 error about missing user info: "openid profile email"
Comprehensive checklist
Here's a handy step-by-step guide to help troubleshoot your configuration if something isn't working. It's a streamlined checklist based on all the setup we did throughout this blog. Be sure to confirm:
In CIAM
- Your Edge API is registered in CIAM with an Audience ID
- Your Application is registered in CIAM with the "Active" state toggled on
- Your Application settings list the callback url(s) for your client app
- Your Application has the correct authentication method ("None") under Advanced Settings
- Your Application has your Edge API selected under Roles & Permissions
- Your Application includes your CIAM user under Access Rules
In AMS
- Your Edge API's Access tab contains the audience ID from CIAM
In Innovator
- Your CIAM user corresponds to an Innovator user with matching email
- Your Innovator user has permissions for the use case you're testing
In the client app
- Your client app uses the correct auth url and scopes when requesting an auth token
- Your client app uses the client ID and client secret from your CIAM Application when requesting an auth token
- Your client app includes the CIAM token in the Authorization header of your HTTP request (prefixed with "Bearer ")
- Your HTTP request url matches the execution url in your Edge API schema
- Your Edge API schema allows the HTTP action for the entity in your HTTP request
If you're still running into trouble or you're looking for more detail, check out these handy sections in the InnovatorEdge docs: Managing Access Tokens, HTTP Request Cookbook, CIAM Applications
What's next
Now that Postman is set up with CIAM and an Edge API, you have a live example of the user auth flow working in a client app. That means you can login as a user and interact with PLM data through a secure, scoped API. It's a solid proof of concept and handy tool to have in your back pocket, but a simple HTTP client isn't going to address your users' needs. Not to worry - this blog is only the second in a series all about delivering connected apps and experiences backed by the power of your digital thread and InnovatorEdge.
The next post picks up right here: diving into Edge Builder and scaffolding a mobile-friendly task app, using your Edge API and the auth flow you just configured. If you've got questions about InnovatorEdge or configuring CIAM in the meantime, drop them on the Aras community forums. We're happy to help and eager to hear what you're building.
