CodeIgniter Shield RESTful API

[miguel-rn]

Shield currently provides two methods of authentication, session and access tokens. There is already boilerplate controllers for authenticating via session. I think there could be interest in having a controller available "out of box" to provide a proper RESTful API for access token authentication.

[lonnieezell]

What type of methods would you like to see in that controller?

Most of the auth token authentication is handled within the tokens filter.

[sammyskills]

Access tokens don't really have a login/logout scenario. They're intended for stateless usage, and the raw token is only ever made available when it's generated so either...

If I am creating an API for a mobile app, at least, a logout endpoint should be provided. This I have seen with a lot of apps.
What I expect this endpoint to do, is to:

1. Delete the current "session" (if this is correct),
2. Revoke the access token, so the user will need to generate a new one for the next login.

I believe the issue here is a misunderstanding of how Access Tokens are used, which we could maybe do a better job of clarifying.

Yes, I totally agree with you. With this, devs will be able to determine if shield fits the scope of what they want to build or not.

I am currently building an API for the mobile app version of a website built using shield, so, I'm wondering, based on the endpoints that I want to create, will shield do this for me, or should I just use PHP JSON Web Tokens ?

[miguel-rn]

generate access tokens via credentials

Can you explain what you mean by credentials? I ask because there's already a way to generate access tokens by supplying the device_name.

This would authenticate a user and if valid, return an access token. This would be used for a mobile app to login.

Access tokens don't really have a login/logout scenario. They're intended for stateless usage, and the raw token is only ever made available when it's generated so either...

If I am creating an API for a mobile app, at least, a logout endpoint should be provided. This I have seen with a lot of apps.
What I expect this endpoint to do, is to:

1. Delete the current "session" (if this is correct),
2. Revoke the access token, so the user will need to generate a new one for the next login.

To clarify, there is no session used with access tokens. And yes, this is why there should endpoints to provide this functionality for access tokens.

[lonnieezell]

I can see this working if we included those routes under a separate function. So, instead of auth()->routes(), we would have auth()->apiRoutes(), and then be able to specify the type of routes, like mobile or something. That makes it easier for people to opt-in to routes and not leave it wide open unintentionally.

[sammyskills]

This would authenticate a user and if valid, return an access token. This would be used for a mobile app to login.

An example has already been given about this. See Issuing the Tokens.

[sammyskills]

Hi @lonnieezell,

Is this something already in the pipeline or your Todo list? If not, I'll suggest you help out with answers to the questions below, so someone else (@miguel-rn or @sammyskills) can take it up.

• What are the required Shield setup instructions for API implementation?
• Is the registration/activation process different from the site/web/traditional flow?
• When/where is the appropriate time/place to use auth('tokens') instead of auth() ?
• What is/are the appropriate way(s) to log a user out of the application completely?

@miguel-rn, if there are other questions that needs to be included, please do so.

Thank you.

[lonnieezell]

@sammyskills It's not currently on my todo list. Too many other pots on the fire at the moment. One thing we'll have to do is force a response format with the api endpoints, so we should use JSON, and maybe even the JSON-API spec?

What are the required Shield setup instructions for API implementation?

That's part of what would need to be determined while we're implementing this. The only thing that are top of mind to me are:

• ensure either chain or tokens is the active auth handler, though for our login/register methods, they would not use any authentication.

I would add a configuration option for apiPath to the Auth config file with a default value of api/auth which would then be used in the new auth()->apiRoutes() method.

Is the registration/activation process different from the site/web/traditional flow?

That really depends on the apps setup. As I've said there are two different flows we should account for - both of them already with explanations in the guides. I can see a use for register/login/logout API endpoints, though, that would basically be the same logic as the existing elements, but would return JSON.

When/where is the appropriate time/place to use auth('tokens') instead of auth() ?

The argument in the the auth() helper selects the handler to use (either session or tokens). So if more than one handler is active, like with the chain auth flow, and you need to use a specific handler, then you need to specify which one by passing its alias in. For example, if you have chain auth on because you want to use the same codebase for the admin area and the api, then when you're in the admin you might specify auth('session') while working in the api would need to access the Access Tokens directly, so you'd use auth('tokens').

What is/are the appropriate way(s) to log a user out of the application completely?

The only way to "log someone out" of using an access token is to revoke the access token

[sammyskills]

Thanks @lonnieezell for the detailed breakdown.

Please consider this statement:

It would be difficult to implement while considering all aspects such as that some users may want to utilize the access tokens for third-party API authorization and not authentication. So we should leave it to developers on how they would like to use the access tokens.

Is this the initial idea you had while creating the PAT feature?

[miguel-rn]

@lonnieezell
@sammyskills

I understand the initial confusion now and think that an authentication API for access tokens may not be worthwhile. It would be difficult to implement while considering all aspects such as that some developers may want to utilize the access tokens for third-party API authorization and not authentication. So we should leave it to developers on how they would like to use the access tokens.

However, I don't want to give up on the idea of an out of box RESTful API for authentication.

Is there a plan for implementing JWT at some point? That would work much better for this use case.

Opinions?

[kenjis]

I believe that #195 is very close to completion.

[datamweb]

@kenjis thanks, I will return to it with a few days delay.

[sammyskills]

@kenjis, any ETA on the completion?

[kenjis]

What is ETA? If more than two people approve, I'm going to merge it.

[sammyskills]

What is ETA?

Expected Time of Arrival.

If more than two people approve, I'm going to merge it.

Thank you for your efforts.

[miguel-rn]

I am having trouble wrapping my head around the architecture of Shield. Let's anticipate I (and/or others) would like to use CodeIgniter Shield in their back-end that is consumed by a mobile app or other front-end service. For example, mobile app sends email and password credentials to an endpoint - am I forced to utilize the session authenticator to check email/pass credentials (when wanting to use other authenticators such as access tokens or JWT (#195)? For example, in the docs, the auth()->attempt() method is used to create a session just to be returned an access token. To me, it seems like a bit of a conflict unless I am misunderstanding something. I would appreciate any clarification to such use case or if there is any plans to do this type of auth in a cleaner way.

[lonnieezell]

No, you're not forced to use Session authenticator, but if you don't you'll need to roll your own validation of the user for login/registration as it currently stands.

The process is this:

1. Session-based authentication is used for all email/password type logins. This is the initial protection to prove who they are and that they're allowed to be given another way to authenticate. This also determines the user account to associate the token with.
2. Once you've authenticated with that handler they're handed a token that is a different way to authenticate. Once they have this token, all authentication for future API calls happens through the Access Token layer until the token expires or is revoked, at which point they would have to prove who they are once again, before being given access to the Access Token method of authentication.

I get that it seems strange to use both at first, but they each have their different use cases in what they protect and how they function.